Chat Overlay API

This reference lists the options, methods, events, errors, and UI feature keys of @epam/ai-dial-chat-overlay, the host-side library that embeds DIAL Chat 1.x in an iframe. It is for developers who integrate Chat into their own application; for how the overlay works and what Chat must allow, see Chat Overlay.

Install

npm install @epam/ai-dial-chat-overlay

import {
  ChatOverlay,
  ChatOverlayManager,
  OverlayEventType,
  OverlayFeature,
  OverlayAuthUiMode,
  OverlayPosition,
} from '@epam/ai-dial-chat-overlay';

ChatOverlay

new ChatOverlay(root, options) mounts one Chat iframe in root, an element or a selector.

const overlay = new ChatOverlay('#chat-root', {
  domain: 'https://chat.example.com',
  theme: 'dark',
  modelId: 'gpt-4o',
});

await overlay.ready();
await overlay.sendMessage('Hello!');

Options

Option	Type	Description
`domain`	`string`	The full URL of the Chat instance, origin plus an optional path. The library derives the target origin from it.
`requestTimeout`	`number`	Milliseconds to wait for a response. Default `10000`.
`loaderStyles`	`Record<string, string>`	Inline CSS for the loader, except `display`.
`loaderClass`	`string`	An extra CSS class for the loader.
`loaderInnerHTML`	`string`	Custom HTML in place of the default spinner. Pass trusted HTML only.
`loaderHideEvent`	`OverlayEventType`	The event that hides the loader. Default `OverlayEventType.Ready`; use `ReadyToInteract` to keep it until Chat is usable.
`enabledFeatures`	`OverlayFeature[]`	The UI features of this embed. It replaces the server's default set. See UI feature keys.
`theme`	`string`	The ID of a theme from the deployment's themes configuration.
`modelId`	`string`	A deployment ID or reference to select. It stays the default for every new chat in the session and outranks the user's own preference; an unknown ID is ignored.
`overlayConversationId`	`string`	The conversation to load.
`auth`	`object`	Sign-in options. See Authentication options.
`signInOptions`	`object`	Deprecated. The legacy `{ autoSignIn, signInProvider, signInInNewWindow }` shape, translated into `auth`.

setOverlayOptions() changes only theme, modelId, overlayConversationId, enabledFeatures, and auth at runtime. It can be called before ready(), because the handshake uses it.

Methods

Method	Description
`ready()`	Resolves after `READY_TO_INTERACT`. Calls made earlier are queued; a queued call's timeout starts when it is sent.
`getMessages()`	Returns the messages of the active conversation.
`sendMessage(content)`	Sends a message to the active conversation.
`setInputContent(content)`	Replaces the composer text.
`setSystemPrompt(prompt)`, `setTemperature(value)`	Apply to the next message, not to a generation in progress.
`getConversations()`	Returns the current conversation list, without a refresh.
`getSelectedConversations()`	Returns the active conversation, or an empty array while the composer is open.
`selectConversation(id)`	Selects a conversation and waits for it to load.
`createConversation({ deploymentId?, firstMessage? })`	Creates and opens a conversation. Without `firstMessage`, it only opens the composer, like `createLocalConversation()`.
`createLocalConversation()`	Opens the composer without saving a conversation.
`renameConversation(id, newName)`, `deleteConversation(id)`	Rename or delete a conversation.
`setOverlayOptions(options)`	Changes the mutable options. `enabledFeatures` replaces the previous set.
`subscribe(eventType, callback)`	Subscribes to an event and returns an unsubscribe function.
`allowFullscreen()`, `openFullscreen()`	Allow and open fullscreen.
`destroy()`	Rejects pending requests and removes the iframe, the loader, and the listener. Safe to call twice.

getMessages() and sendMessage() return messages with an optional stages array: the agent's tool calls, retrieval steps, and reasoning steps, each with index, name, status, and optional content and tag. To inspect a finished answer, subscribe to GptEndGenerating and call getMessages().

Events

Event	Fires when
`InitReady`	At once, before the host is known.
`Ready`	Chat has resolved sign-in and loaded its models.
`ReadyToInteract`	Once, after the first conversation is selected or the composer is ready.
`SelectedConversationLoaded`	A conversation finishes loading.
`GptStartGenerating`	A generation starts in the active conversation.
`GptEndGenerating`	A generation completes, but not when the user stops it.
`StopGenerating`	The user or the host stops a generation.
`ConversationsUpdated`	The conversation list changes.

Errors

A request Chat cannot run rejects at once with ChatOverlayRequestError; read its code and requestType.

`OverlayRequestErrorCode`	Raised when
`ACTIVE_CONVERSATION_UNAVAILABLE`	An active-conversation method is called while the empty composer is open.
`CONVERSATION_LIST_UNAVAILABLE`	A conversation-list method is called on a screen without the conversation list.
`INVALID_PAYLOAD`	The request does not match the method, for example a missing conversation ID.
`REQUEST_EXECUTION_FAILED`	Chat accepted the request and failed while running it.

Separately, selectConversation, createConversation, renameConversation, and deleteConversation return an optional error with code NOT_FOUND, FORBIDDEN, or INVALID_ARGUMENT.

Authentication options

const overlay = new ChatOverlay('#chat-root', {
  domain: 'https://chat.example.com',
  auth: {
    providerUiModes: {
      'azure-ad': OverlayAuthUiMode.External,
      keycloak: OverlayAuthUiMode.SameWindow,
    },
    autoSignInProvider: 'keycloak',
  },
});

providerUiModes maps provider IDs — auth0, azure-ad, azure-b2c, gitlab, google, keycloak, ping-id, cognito, okta — to a login mode. External, the default for every omitted provider, opens login in a new tab. SameWindow runs it inside the iframe.
autoSignInProvider starts that provider's login with no user action. The provider must be mapped to SameWindow, because a browser blocks the new tab of External without a user gesture.
With an empty map, the overlay shows one Log in button that opens the standard login page.

ChatOverlayManager

ChatOverlayManager creates floating widgets and forwards every ChatOverlay method, keyed by overlayId.

const manager = new ChatOverlayManager();

manager.createOverlay({
  overlayId: 'support-widget',
  domain: 'https://chat.example.com',
  position: OverlayPosition.RightBottom,
  width: 380,
  height: 600,
  allowFullscreen: true,
});

await manager.sendMessage('support-widget', 'Hello!');
manager.hideOverlay('support-widget');
manager.showOverlay('support-widget');
manager.removeOverlay('support-widget');
manager.destroy();

It takes every ChatOverlay option plus overlayId (required), position (default RightBottom), width and height (default 380 × 600, a number in pixels or a string), zIndex (default 999999), allowFullscreen, and the accessible labels toggleButtonAriaLabel, closeButtonAriaLabel, and fullscreenButtonAriaLabel.

UI feature keys

enabledFeatures takes OverlayFeature values, which are the keys of ENABLED_UI_FEATURES:

Omitting enabledFeatures keeps the server's set. [] replaces it with an empty set.
Every call replaces the previous set, so always send the complete list.
Unknown values are dropped with a console warning; custom-applications still resolves to schema-apps.

Legacy keys

Legacy key	In Chat 1.x
`marketplace`, `marketplace-hide-my-apps`, `marketplace-table-view`	Renamed to `catalog`, `catalog-hide-my-apps`, `catalog-table-view`. The old names are not recognized.
`custom-applications`	Renamed to `schema-apps`; still accepted for now.
`custom-logo`, `show-layout-dividers`, `chat-header-border`, `chat-input-border`, `user-message-align-end`	Gone; the behavior is always on.
`top-settings`	Gone; the same settings live in the input's + menu, controlled by `chat-settings`.
`top-chat-model-settings`	Gone; use `hide-change-agent` or `disallow-change-agent`.
`prompts-section`, `prompts-panel-toggle`, `showPromptsSectionByDefault`, `prompts-sharing`, `prompts-publishing`, `footer`, `top-chat-info`, `top-clear-conversation`, `hide-top-context-menu`, `report-an-issue`, `request-api-key`, `message-templates`, `code-interpreter`, `compare-mode-disabled`, `input-links`, `chat-full-width-by-default`, `edit-all-assistant-message`, `edit-last-assistant-message`, `disabled-playback-controls`, `md-sidebar-overlay-breakpoint`	Not supported yet.

Styling

The library injects one <style id="dial-overlay-styles"> element and uses these classes:

Class	Applied to
`dial-overlay-root`	The root element, when its `position` is `static`
`dial-overlay-iframe`	The Chat iframe
`dial-overlay-loader`	The loader
`dial-overlay-loader--hidden`	The loader once `loaderHideEvent` arrives

Set these custom properties on any ancestor of the root to recolor the loader and the manager's buttons:

Custom property	Default
`--dial-overlay-loader-background`	`#ffffff`
`--dial-overlay-loader-color`	`#2764d9`
`--dial-overlay-btn-background`	`#2764d9`
`--dial-overlay-btn-color`	`#ffffff`
`--dial-overlay-btn-background-hover`	`#1d4fb8`
`--dial-overlay-btn-outline`	`#1d4fb8`

Do not drive the loader's visibility with display; set loaderHideEvent instead.

Install​

ChatOverlay​

Options​

Methods​

Events​

Errors​

Authentication options​

ChatOverlayManager​

UI feature keys​

Legacy keys​

Styling​

Further reading​