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 to be used. Unless directed by an Ada team member, you should not change this value.

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.

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
});

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
});

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
}

FlatObject

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

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
}