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.

1
<script>
2
  window.adaSettings = {
3
    ...
4
  }
5
</script>
6
...
7
<!-- Define the web chat script afterwards -->

Alternatively, you can pass settings to the adaEmbed.start method. (See Delay bot loading.)

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.

1
<script type="text/javascript">
2
  window.adaSettings = {
3
    adaReadyCallback: ({ isRolledOut }) => {
4
      console.log("Ada Embed is done setting up. Chat support is now available.");
5
    }
6
  }
7
</script>

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, att). 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.

1
<script type="text/javascript">
2
window.adaSettings = {
3
  conversationEndCallback: (event) => {
4
    // perform action after conversation has been ended by the chatter
5
  }
6
};
7
</script>

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).

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

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, and setDelegate.
• Receive the ada:message:sent and ada:message:received events 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.

1
window.adaSettings = {
2
  handle: "<your-bot-handle>",
3
  enableProgrammaticControl: true,
4
};

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:

• setComposerText rejects with HeadlessModeError — there is no built-in composer to write to.
• toggle is a no-op — there is no drawer to open or close.
• isOpen always returns false.

1
window.adaSettings = {
2
  handle: "<your-bot-handle>",
3
  headless: true,
4
  enableProgrammaticControl: true,
5
};

hideMask

hideMask?: boolean;

When set to true, prevents the default mask from appearing on top of your site’s content when opened on desktop.

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:

1
<script>
2
      window.adaSettings = {
3
        language: "fr",
4
      }
5
    </script>

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.

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.

1
<script type="text/javascript">
2
  window.adaSettings = {
3
    metaFields: {
4
      phone_number: "(123) 456-7890",
5
      name: "Ada Lovelace"
6
    }
7
  }
8
</script>

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.

1
<script type="text/javascript">
2
window.adaSettings = {
3
  onAdaEmbedLoaded: () => {
4
    window.adaEmbed.subscribeEvent("ada:campaigns:shown", (data) => {
5
      console.log("Message received from campaign with key:", data.campaignKey);
6
    });
7
  }
8
};
9
</script>

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.

1
<head>
2
  <!-- ... -->
3
  <script type="text/javascript">
4
    window.adaSettings = {
5
      parentElement: document.getElementById("custom-iframe")
6
    }
7
  </script>
8
</head>
9
<body>
10
  <!-- ... -->
11
  <div id="custom-iframe"></div>
12
</body>

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.

1
<script type="text/javascript">
2
  window.adaSettings = {
3
    sensitiveMetaFields: {
4
      jwt_token: "xxxxx.yyyyy.zzzzz",
5
    }
6
  }
7
</script>

To change these values after bot setup, use the setSensitiveMetaFields action.

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.

1
window.adaSettings = {
2
  zdChatterAuthCallback: (callback) => {
3
    // Here you should make a request to get the fresh JWT token
4
    const token = "token goes here";
5
    callback(token)
6
  }
7
};

1
window.adaSettings = {
2
    handle: "<YOUR-BOT-HANDLE>",
3
    cluster: "<YOUR-CLUSTER>",
4
    zdChatterAuthCallback: (callback) => {
5
        if (userLoggedIn) {
6
            const token = "token goes here";
7
            callback(token)
8
        }
9
10
        callback()
11
    }
12
};

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).

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: if ignoreFrequency is true, trigger conditions for Campaigns that have already been triggered within the configured frequency are also evaluated and may be triggered.
• ignoreStatus?: boolean: if ignoreStatus is true, trigger conditions for inactive and draft Campaigns are also evaluated and may be triggered.

getInfo

getInfo(): Promise<WindowInfo>;

Returns a WindowInfo object containing information about the bot. See WindowInfo for more details.

1
window.adaEmbed.getInfo().then(function(windowInfo){
2
    console.log("is the drawer open?");
3
    console.log(windowInfo.isDrawerOpen ? "Yes": "No");
4
});

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.

1
const conversation = await window.adaEmbed.getConversation();
2
console.log("Conversation id:", conversation.id);
3
if (conversation.handoff.inLiveChat) {
4
  console.log("Talking to agent:", conversation.handoff.agent?.name);
5
}

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 role of "user", "bot", or "agent".

1
const messages = await window.adaEmbed.getMessages();
2
messages.forEach((m) => console.log(`[${m.role}] ${m.body ?? "<no body>"}`));

getMetaFields

getMetaFields(): Promise<FlatObject>;

Returns the metaFields currently set on the active chatter — the values passed to start({ metaFields }) plus any subsequent setMetaFields updates.

1
const meta = await window.adaEmbed.getMetaFields();

isOpen

isOpen(): Promise<boolean>;

Resolves to true when the chat drawer is open, and false otherwise. Always returns false in headless mode.

1
if (!(await window.adaEmbed.isOpen())) {
2
  window.adaEmbed.toggle();
3
}

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, metaFields, sensitiveMetaFields, and greeting for the new chatter.

1
window.adaEmbed.reset({
2
  greeting: "5e9481e296ac6c4467092be5"
3
});

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 — text is empty or whitespace-only.
• DelegateRejected — a registered beforeSend hook returned false.
• DelegateTimeout — the beforeSend hook did not resolve within 5 seconds.
• sendMessage rejected by chat: <CODE> — chat-side validation rejected the message. Codes include TOO_LONG (exceeds the generative composer cap of 500 characters), RATE_LIMITED (a previous send is still in flight), and EMPTY_TEXT.

To attach metadata to the conversation, use setMetaFields before calling sendMessage.

1
const { id } = await window.adaEmbed.sendMessage("What is your refund policy?");
2
console.log("Sent message id:", id);

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.

1
window.adaEmbed.setComposerText("Hello, I'd like to ask about ");

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 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 to false) to cancel. sendMessage rejects with DelegateRejected.
• 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.

1
window.adaEmbed.setDelegate({
2
  beforeSend: ({ text }) => {
3
    if (text.toLowerCase().includes("secret")) return false;
4
    return { text: text.trim() };
5
  },
6
});

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.

1
window.adaEmbed.setLanguage("en");

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.

1
window.adaEmbed.setMetaFields({
2
  phone_number: "(123) 456-7890",
3
  name: "Ada Lovelace"
4
});

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.

1
window.adaEmbed.setSensitiveMetaFields({
2
  jwt_token: "xxxxx.yyyyy.zzzzz",
3
});

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).

1
window.adaEmbed.start({
2
  handle: "my-bot",
3
  language: "fr",
4
  mobileOverlay: true
5
});

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.

1
window.adaEmbed.subscribeEvent("ada:campaigns:shown", (data) => {
2
  console.log("Message received from campaign with key:", data.campaignKey);
3
});

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.

Two arguments are provided to each callback when it is called: data and context:

• data is specific to each event.
• context is an object with a single property, the eventKey of the event that triggered the callback.

1
window.adaEmbed.subscribeEvent("ada:campaigns", (data, context) => {
2
  const { eventKey } = context;
3
4
  if (eventKey === "ada:campaigns:shown") {
5
    console.log("Message received from campaign with key:", data.campaignKey);
6
  }
7
8
  if (eventKey === "ada:campaigns:opened") {
9
    console.log("Chat opened after being shown campaign with key:", data.campaignKey);
10
  }
11
12
  if (eventKey === "ada:campaigns:engaged") {
13
    console.log("Chatter engaged with campaign with key:", data.campaignKey);
14
  }
15
});

subscribeEvent returns a number subscriptionId that you can use to unsubscribe later (see unsubscribeEvent).

1
window.adaEmbed.subscribeEvent("ada:end_conversation", (data, context) => {
2
    console.log("The conversation has been ended by the user.");
3
    console.log("Chatter ID: ", data.chatter_id);
4
    console.log("Chat Data: ", data.event_data);
5
    console.log("Chat Transcript: ", data.event_data.chatter_transcript);
6
    });

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.

1
window.adaEmbed.subscribeEvent("ada:chat_frame_timeout", (data, context) => {
2
  // Perform logic needed here when chat fails to load.
3
});

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

window.adaEmbed.triggerAnswer("627d28a9bd9ca9e5337b9763");

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.

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

1. Triggering a static Proactive Conversation

   Ex: “Hello, how can I help you today?”

1
window.adaEmbed.triggerProactive({
2
  messageKey: "static_message_key"
3
});

2. Triggering a template Proactive Conversation

   Ex: “Hello {{name}}, how can I help you today?”

1
window.adaEmbed.triggerProactive({
2
  messageKey: "template_message_key",
3
  params: { name: "Ada" }
4
});
5
6
// -> "Hello Ada, how can I help you today?"

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.

1
window.adaEmbed.trackEvent("Example_Event", 2, {
2
  productId: "a1b2c3",
3
  customerSegment: "premium"
4
});

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.

1
const subscriptionId = await window.adaEmbed.subscribeEvent("ada:campaigns:shown", (data) => {
2
  console.log("Message received from campaign with key:", data.campaignKey);
3
});
4
5
window.adaEmbed.unsubscribeEvent(subscriptionId);

Type signatures

Embed2 actions commonly use the following type signatures.

CampaignParams

1
{
2
  ignoreFrequency?: boolean
3
  ignoreStatus?: boolean
4
}

ConversationInfo

1
{
2
  id: string | null;
3
  handoff: {
4
    inLiveChat: boolean;
5
    agent?: { id: string; name: string; avatarUrl?: string };
6
  };
7
}

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

1
{
2
  beforeSend?: (message: { text: string }) =>
3
    { text: string } | false | Promise<{ text: string } | false>;
4
}

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

1
{
2
  [key: string]\: string | number | boolean | null
3
}

Message

1
{
2
  id: string;
3
  role: MessageRole;        // "user" | "bot" | "agent"
4
  type: string;             // "text", "picture", "link", "quick_replies", "csat", etc.
5
  body?: string;            // omitted for non-text messages
6
  createdAt: number;        // Unix epoch seconds, sub-second precision
7
  agent?: { id: string; name: string; avatarUrl?: string };  // present on agent messages during a live-agent handoff
8
  data?: Record<string, unknown>;  // type-specific extras (for example, file uploads carry { url, name, mimeType })
9
}

The message shape returned by getMessages and carried in the ada:message:sent and ada:message:received event payloads.

MessageRole

1
"user" | "bot" | "agent"

ResetParams

1
{
2
  greeting?: string;
3
  language?: string;
4
  metaFields?: FlatObject;
5
  sensitiveMetaFields?: FlatObject;
6
}

WindowInfo

1
{
2
  hasActiveChatter: boolean;
3
  hasClosedChat: boolean;
4
  isChatOpen: boolean;
5
  isDrawerOpen: boolean;
6
}