SDK API Reference
Ada’s Web Chat consists of a global adaEmbed object that you must add to your site to use any Web SDK functionality, along with corresponding settings and actions.
Settings
Set the Web Chat’s configurable options by defining an adaSettings object on your window scope.
Alternatively, you can pass settings to the adaEmbed.start method. (See Delay bot loading.)
The Web SDK requires that window.adaSettings be defined before the script loads. You must therefore either define window.adaSettings before the script, or make use of async on your web chat script.
The following are all of the available settings for Web chat.
adaReadyCallback
adaReadyCallback?(params: { isRolledOut: boolean }): void;
Specifies a callback function to be called when Web Chat has finished setting up. This is especially useful when Web Chat is loaded asynchronously.
allowMetaFieldsInReset
allowMetaFieldsInReset?: boolean;
Controls whether reset is allowed to set metaFields and sensitiveMetaFields on the new conversation. When false (the default), any metaFields or sensitiveMetaFields passed to reset are ignored; the reset still applies greeting and language, and clears chat history, as usual. Set this to true only if your integration relies on passing meta fields through reset.
The value is read once, when Chat first loads for a given AI Agent on the page. Calling stop and then start again with a different value does not change it for the remainder of the page load.
reset can be called from the browser console by anyone viewing the page. With allowMetaFieldsInReset: true, an end user can set meta field values to anything they choose on their own conversation. If you use meta fields to drive entitlements such as discounts, vouchers, or account benefits, leave this disabled and set those values from a trusted server-side context instead.
chatterTokenCallback
chatterTokenCallback?(chatter: string): void;
Specifies a callback for when the chatter token has been set in Chat. This is called when chat is first opened by a chatter.
cluster
cluster?: string;
Specifies the Kubernetes cluster your AI Agent runs on.
Set this only if your Agent is hosted on a non-default cluster (e.g., us2, maple, eu).
If the Agent is on the default us cluster, leave this unset.
For more details, see Load a bot on a non-default cluster.
conversationEndCallback
conversationEndCallback?(callback: (event?: { [key]: string | object }) => void): void;
Use conversationEndCallback to specify a callback function to be called when a chatter ends the conversation. The callback will receive an event object containing conversation metadata.
crossWindowPersistence
crossWindowPersistence?: boolean;
When set to true, allows the chat drawer open/close state to persist across windows and page refreshes using the Window.sessionStorage API. When the browser is closed the state is forgotten. Note that the crossWindowPersistence setting only works if an Ada Glass live chat is active (that is, while a chatter is connected to an agent).
We recommend enabling this feature if your bot uses Ada Glass.
domain
domain?: string;
Use this setting to change the subdomain. Unless directed by an Ada team member, you will not need to change this value.
greeting
greeting?: string;
Use to customize the greeting messages that new chatters see. This is useful for setting page-specific greetings across your app. The greeting should correspond to the ID of the Answer you would like to use, which you can find in the URL of the corresponding Answer in the dashboard.
Example

This setting is only applicable if you’re using a scripted bot.
handle
handle:? string;
Can be used to specify the bot handle if one is not specified in the script data-handle attribute.
enableProgrammaticControl
enableProgrammaticControl?: boolean;
Opt-in to the transcript-bearing programmatic surface. When set to true, your page can:
- Call
sendMessage,getMessages,getConversation,setComposerText, andsetDelegate. - Receive the
ada:message:sentandada:message:receivedevents on host-page subscribers.
While the flag is false (the default), those methods reject with ProgrammaticControlNotEnabled and the events are not delivered to host subscribers.
Every script that lives in your host page (analytics tags, GTM, ad pixels, session replay tools, and any third-party SaaS pixel) inherits your page’s trust and can subscribe to these events or call these methods. They will see full message bodies, including any PII your chatters type. Have your product and security teams accept that exposure risk explicitly before turning this on.
headless
headless?: boolean;
When set to true, Chat connects to the bot in the background without rendering the default chat button or drawer. Use this when your page is rendering its own chat UI and driving the conversation through sendMessage, getMessages, getConversation, and subscribeEvent.
Headless sessions are typically paired with enableProgrammaticControl: true — without it the methods needed to drive a custom UI reject at runtime.
Methods that act on the built-in UI are not available in headless mode:
setComposerTextrejects withHeadlessModeError— there is no built-in composer to write to.toggleis a no-op — there is no drawer to open or close.isOpenalways returnsfalse.
Headless sessions run with no visual indicator. The chatter token is created and persisted to local storage the same way as a visible session. If your page is compromised, an attacker can run chatter activity under the visiting user’s token without any user-facing signal — host pages should treat enabling headless as a meaningful trust decision.
hideMask
hideMask?: boolean;
When set to true, prevents the default mask from appearing on top of your site’s content when opened on desktop.
We recommend setting the value of hideMask to false. This allows users to navigate the page while the Ada chat window is open.
language
language?: string;
Set the language for your bot. This setting takes in a language code to programatically set the default bot language. For example, you could change the language to French as in the following example:
You must first turn languages on in your dashboard:
- If you’re using a generative AI Agent, go to Customization > Languages. See Support multiple languages in the same AI Agent.
- If you’re using a scripted bot, go to Settings > Bot Setup > Multilingual. See Support multiple languages in the same bot.
Language codes must use the ISO 639-1 language format.
Alternatively, you can use the setLanguage action, which allows you to change the language without clearing the chat history.
lazy
lazy?: boolean;
When set to true true, this will prevent the bot from loading until the adaEmbed.start(...) method is called. (Alternatively, see Delay bot loading.)
metaFields
metaFields?: FlatObject;
Use metaFields to pass information about a chatter to Ada. This can be useful for tracking information about your customers, as well as personalizing their experience. For example, you may wish to track the phone_number and name for conversation attribution. (See Variables for more information)
Once set, you can access this information:
- in the email attachment from Handoff Form submissions
- via the Meta variables modal in the Conversations page of your Ada dashboard
To change these values after bot setup, use the setMetaFields action.
Meta field keys should not include whitespace, emojis, special characters, or periods.
onAdaEmbedLoaded
Called when the embed script has been loaded, and before it is initialized. This is useful for subscribing to events. Subscribing here ensures that subscriptions are in place before events are triggered.
parentElement
parentElement?: string | HTMLElement;
Specifies where to mount the <iframe> if the default side drawer is not desired. Accepts the HTMLElement or element id of the desired parent element.
Chat will render immediately inside the parentElement provided. This means that the conversation will also get initialized. We do not recommend initializing Embed2 with the parentElement setting automatically on every page, since it could lead to low engagement rates.
privateMode
privateMode?: boolean;
Puts web chat into private mode when set to true. In private mode, web chat forgets conversation history on refresh. This is effectively the same as setting customer persistence or chatter persistence to Forget After Reload.
rolloutOverride
rolloutOverride?: number;
Use this setting to override the rollout value set in the dashboard. This can be useful if you need page-specific rollout values. Accepts any number between 0 and 1.
sensitiveMetaFields
sensitiveMetaFields?: FlatObject;
Like metaFields, you can use sensitiveMetaFields to pass information about a chatter to Ada. With sensitiveMetaFields, however, values are:
- encrypted immediately upon entering the Ada system
- temporarily stored in a cache on the Ada side, that is cleared after 24 hours
- not stored in the database
- redacted on the dashboard
If the sensitive data is sent as part of a bot response, it is not redacted the first time it appears (to allow the chatter to verify it, for example), but the data is redacted when fetching the logs of a recent conversation.
To change these values after bot setup, use the setSensitiveMetaFields action.
Meta field keys should not include whitespace, emojis, special characters, or periods.
testMode
testMode?: boolean;
Marks the chatter as a test user.
toggleCallback
toggleCallback?(isDrawerOpen: boolean): void;
Use this setting to trigger side effects when the web chat drawer is opened or closed.
zdChatterAuthCallback
zdChatterAuthCallback?(callback: (token: string) => void): void;
Use zdChatterAuthCallback for Zendesk chatter authentication. This setting allows you to request a JWT token from your API, then pass it to Ada. This creates shared trust between Ada and Zendesk, and in turn allows for verifiable chatter identity within the context of a chat session.
Ada waits up to 30 seconds for the callback to be triggered before loading chat. If the callback isn’t triggered within that time, Ada abandons the request. If you need to bypass authentication, ensure you call the callback with no arguments.
zdChatterAuthCallback is available only for Zendesk Chat. It is not available for Zendesk Messaging.
Actions
You can call all of the following Embed2 Actions from the global adaEmbed object.
closeCampaign
closeCampaign(): Promise<void>;
Closes the currently displayed campaign (does nothing if no campaign is currently displayed).
This action requires the Ada Pro package.
This action is only applicable if you’re using a scripted bot.
deleteHistory
deleteHistory(): Promise<void>;
Deletes the chatter object used to fetch conversation logs for a user from storage. When a user opens a new chat window, a new chatter object is generated.
evaluateCampaignConditions
evaluateCampaignConditions(options: CampaignParams): Promise<void>;
This is similar to triggerCampaign, however, instead of triggering a specific Campaign, evaluateCampaignConditions evaluates the trigger conditions of the Campaigns in priority order, and triggers the first Campaign whose conditions are matched. This can be useful, for example, if Embed2 cannot determine that the route has changed, and the campaign trigger rules need to be evaluated again.
An optional argument options can be passed that matches the CampaignParams interface. These options settings may be helpful when testing your Campaign:
ignoreFrequency?: boolean: ifignoreFrequencyistrue, trigger conditions for Campaigns that have already been triggered within the configured frequency are also evaluated and may be triggered.ignoreStatus?: boolean: ifignoreStatusistrue, trigger conditions for inactive and draft Campaigns are also evaluated and may be triggered.
This action requires the Ada Pro package.
This action is only applicable if you’re using a scripted bot.
getInfo
getInfo(): Promise<WindowInfo>;
Returns a WindowInfo object containing information about the bot. See WindowInfo for more details.
getConversation
getConversation(): Promise<ConversationInfo>;
Returns information about the active conversation — its id (or null if the chatter hasn’t sent or received any messages yet) and the live-agent handoff state. See ConversationInfo for the full shape.
Requires enableProgrammaticControl: true. Otherwise rejects with ProgrammaticControlNotEnabled.
getMessages
getMessages(): Promise<Message[]>;
Returns the messages currently held in the chat session, in the order they were sent. See Message for the field shape.
Requires enableProgrammaticControl: true. Otherwise rejects with ProgrammaticControlNotEnabled.
Important behaviors:
- In-memory only. This is the list the embed has rendered for the current chatter — there is no server-side history endpoint or pagination. Refreshing the page resets the list to whatever the embed rehydrates from the chatter token.
- Filtered to conversational messages. Presence notifications (typing, conversation-ended), system events, and other non-conversational entries are excluded. Every returned message has a
roleof"user","bot", or"agent".
getMetaFields
getMetaFields(): Promise<FlatObject>;
Returns the metaFields currently set on the active chatter — the values passed to start({ metaFields }) plus any subsequent setMetaFields updates.
isOpen
isOpen(): Promise<boolean>;
Resolves to true when the chat drawer is open, and false otherwise. Always returns false in headless mode.
reset
reset(resetParams?: ResetParams): Promise<void>;
Creates a new chatter and refreshes the Chat window. reset can take an optional object allowing you to change the language and greeting for the new chatter.
By default, metaFields and sensitiveMetaFields passed to reset are ignored. To apply them, opt in with the allowMetaFieldsInReset setting. Review the security note in that setting before enabling it.
sendMessage
sendMessage(text: string): Promise<{ id: string }>;
Sends a message to the bot on behalf of the chatter. Resolves with the new message’s id, which matches the id you’ll see on the same message in getMessages and in the ada:message:sent event payload.
Requires enableProgrammaticControl: true. Otherwise rejects with ProgrammaticControlNotEnabled.
Possible rejections:
sendMessage requires non-empty text—textis empty or whitespace-only.DelegateRejected— a registeredbeforeSendhook returnedfalse.DelegateTimeout— thebeforeSendhook did not resolve within 5 seconds.sendMessage rejected by chat: <CODE>— chat-side validation rejected the message. Codes includeTOO_LONG(exceeds the generative composer cap of 500 characters),RATE_LIMITED(a previous send was too recent), andEMPTY_TEXT.
To attach metadata to the conversation, use setMetaFields before calling sendMessage.
setComposerText
setComposerText(text: string): Promise<void>;
Pre-fills the chat composer with text without sending it. The chatter can still edit or clear the text before sending.
Requires enableProgrammaticControl: true. Otherwise rejects with ProgrammaticControlNotEnabled. Not available in headless mode (rejects with HeadlessModeError). Rejects with setComposerText rejected by chat: TOO_LONG if text exceeds the visible composer’s 500-character cap.
setDelegate
setDelegate(delegate: Delegate): void;
Registers a beforeSend hook that runs on outgoing messages sent via sendMessage. Use it to transform, cancel, or pass the message through.
Requires enableProgrammaticControl: true. Otherwise throws synchronously with ProgrammaticControlNotEnabled.
The hook fires only for programmatic sendMessage() calls. Messages typed into the chat composer (when the visible UI is in use) are sent through a separate path and do not flow through beforeSend. Do not rely on this hook as a moderation or PII-redaction gate for composer input — it will not see those messages.
The hook receives { text: string } (not a full Message) and returns one of:
- A modified
{ text: string }to change what’s sent. false(or a Promise resolving tofalse) to cancel.sendMessagerejects withDelegateRejected.- The input unchanged to pass through.
The hook can be synchronous or asynchronous. It is bounded by a 5-second timeout — a slow or never-resolving delegate causes sendMessage to reject with DelegateTimeout. The transformed text is re-validated: returning { text: "" } or { text: " " } causes sendMessage to reject (the message is not sent).
Set beforeSend to undefined to clear the hook.
See Delegate for the type shape.
setLanguage
setLanguage(language: string): void;
Changes the language in chat programatically. Use this action, rather than the language setting, to change the chat language without clearing the chat history. Language codes must use a lowercase, two-letter code, in ISO 639-1 language format. For example, en, fr, ca, ar, and so on.
Before using setLanguage:
-
You must turn languages on in your Ada dashboard.
- If you’re using a generative AI Agent, go to Customization > Languages. See Support multiple languages in the same AI Agent for more information.
- If you’re using a scripted bot, go to Settings > Bot setup > Multilingual. See Support multiple languages in the same bot for more information.
-
The chat window must be opened at least once.
setMetaFields
setMetaFields(fields: FlatObject): Promise<void>;
Used to update metaFields after chat has been opened. In most situations, the metaFields settings object should be enough for user attribution. However, in cases where Ada chat remains open while page changes occur (like in Single Page Applications), this method may be useful.
Meta field keys should not include whitespace, emojis, special characters, or periods.
setSensitiveMetaFields
setSensitiveMetaFields(fields: FlatObject): Promise<void>;
Use this action to update sensitiveMetaFields after chat has been opened. Here, the values are not stored in the database and are deleted after 24 hours.
Meta field keys should not include whitespace, emojis, special characters, or periods.
start
start(adaSettings: StartOptions): Promise<void>;
Used to initialize Embed2 on your page. This action is triggered by default internally, so you will typically not need to call it directly unless you are using Embed2 in lazy mode, or have called stop and want to restart Embed2.
StartOptions matches anything listed in the Settings section (for example, adaReadyCallback).
stop
stop(): Promise<void>;
Removes Embed2 from your page.
subscribeEvent
subscribeEvent(eventKey: string, callback: (data: object, context: object) => void): Promise<number>
Certain things in Ada trigger events. Each event consists of an event key and a data payload. Using subscribeEvent, you can define callbacks that are called when a specific event is triggered.
Callbacks are triggered whenever an event starts with the eventKey provided to subscribeEvent. This means you can subscribe to all events of a certain category. For example, the callback in a subscription to ada:campaigns will be called on ada:campaigns:shown, ada:campaigns:opened, and any other events beginning with ada:campaigns.
Transcript-bearing events are the exception: ada:message:sent and ada:message:received require exact subscriptions to those event keys. They aren’t delivered through prefix subscriptions such as ada:message or broad listeners such as subscribeAll, so transcript data isn’t exposed to generic host-page subscribers.
Two arguments are provided to each callback when it is called: data and context:
datais specific to each event.contextis an object with a single property, theeventKeyof the event that triggered the callback.
subscribeEvent returns a number subscriptionId that you can use to unsubscribe later (see unsubscribeEvent).
It is strongly recommended that you place initial subscriptions to events in the onAdaEmbedLoaded function. This ensures that:
- the embed script has been loaded, so it is available to accept subscriptions.
- subscriptions happen before any events are triggered, so that no events are missed.
The following are the events that you can currently subscribe to:
The events that begin with ada:agent are compatible with the following handoffs:
- Zendesk Messaging
- Zendesk Live Chat
- Salesforce
- Nuance
- Aysnchronous handoffs (via Ada’s Solutions team)
toggle
toggle(): Promise<void>;
Used toggle to programatically open or close the chat window. You cannot use this method with the parentElement option.
triggerAnswer
triggerAnswer(answerId: string): void;
Triggers an answer in chat. Include the Answer ID, which you can find in the URL of the corresponding Answer in the dashboard.
Example

The chat window must be opened at least once before this method can be used.
This action is only applicable if you’re using a scripted bot.
triggerCampaign
triggerCampaign(campaignKey: string, options: CampaignParams): Promise<void>;
Use in conjunction with campaignKey to trigger proactive campaigns. It supports two optional arguments:
ignoreFrequency?: boolean: when set to true, allows campaign triggering even if it’s already been triggered within the frequency configured in the dashboard campaign settings.ignoreStatus?: boolean: when set to true, allows campaign triggering even if it’s inactive or in a draft state.
In most cases, you should set these to false, so that the original settings configured for the campaign take precedence. There may be specific cases in which you might enable ignoreFrequency. For example, a campaign that is shared across multiple pages, that you want to show once on a single page (such as the main page of a help center), but show once per session on all subpages.
See Embed Campaign Use Cases for some examples of how to use this action.
This action requires the Ada Pro package.
This action is only applicable if you’re using a scripted bot. For a generative AI Agent, see triggerProactive instead.
triggerProactive
triggerProactive({ messageKey: string, params?: Record<string, string> }): void;
Triggers a proactive conversation using a specified key. This will display predefined static or template messages, where template messages can include dynamic parameters.
Parameters
Examples
-
Triggering a static Proactive Conversation
Ex: “Hello, how can I help you today?”
-
Triggering a template Proactive Conversation
Ex: “Hello {{name}}, how can I help you today?”
This action is only applicable if you’re using a generative AI Agent. For a scripted bot, see triggerCampaign instead.
This action is only applicable if you’re using a generative AI Agent.
trackEvent
trackEvent(eventKey: string, value?: number, meta?: FlatObject)
Use this to track an Event. The arguments of this function are:
eventKey: string: the key of the Event to track (required).value?: number: an optional value to assign to the Event.meta?: FlatObject: an optional object containing metadata corresponding to the Event. For example, it may be useful to track information such as currency, product group, customer segment, and so on.
This action requires the Ada Pro package.
unsubscribeEvent
unsubscribeEvent(subscriptionId: number): void;
Use this function to remove subscriptions created with the subscribeEvent function. It takes a single parameter, subscriptionId, which is the id of the subscription to be removed.
Type signatures
Embed2 actions commonly use the following type signatures.
CampaignParams
ConversationInfo
The shape returned by getConversation. id is the id of the active conversation, or null if the chatter hasn’t sent or received any messages yet. handoff.agent is populated only during an active live-agent handoff.
Delegate
The object accepted by setDelegate. beforeSend is called for messages sent via sendMessage only (not composer-typed messages) — return { text } to change it, false to cancel it (causing sendMessage to reject with DelegateRejected), or pass the input through unchanged. Bounded by a 5-second timeout.
FlatObject
Message
The message shape returned by getMessages and carried in the ada:message:sent and ada:message:received event payloads.