Embed2 consists of a global adaEmbed object that you must add to your site to use any Embed2 functionality, along with corresponding settings and actions.
Settings
Set Embed2's configurable options by defining an adaSettings object on your window
scope.
<script>
window.adaSettings = {
...
}
</script>
...
<!-- Define the Embed script afterwards -->
Alternatively, you can pass settings to the adaEmbed.start method. (See Delay bot loading.)
Embed2 requires that
window.adaSettings
be defined before the script loads. You must therefore either definewindow.adaSettings
before the Embed script, or make use of async on your embed script (see Async).
The following are all of the available settings for Embed2.
adaReadyCallback
adaReadyCallback?(params: { isRolledOut: boolean }): void;
Specifies a callback function to be called when Embed2 has finished setting up. This is especially useful when Embed2 is loaded asynchronously.
<script type="text/javascript">
window.adaSettings = {
adaReadyCallback: ({ isRolledOut }) => {
console.log("Ada Embed is done setting up. Chat support is now available.");
}
}
</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.
<script type="text/javascript">
window.adaSettings = {
conversationEndCallback: (event) => {
// perform action after conversation has been ended by the chatter
}
};
</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).
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
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.
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:
<script>
window.adaSettings = {
language: "fr",
}
</script>
You must first turn languages on under Settings > Bot Setup > Multilingual on your Ada dashboard. 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, or this use case that illustrates the idea of passing metaFields into Ada and using them within answers.)
Once set, you can access this information:
- in the email attachment from Handoff Form submissions
- via the Chatter Info modal in the Conversations page of your Ada dashboard
To change these values after bot setup, use the setMetaFields action.
<script type="text/javascript">
window.adaSettings = {
metaFields: {
phone_number: "(123) 456-7890",
name: "Ada Lovelace"
}
}
</script>
Meta field keys should not include whitespace, emojis, special characters, or periods.
onAdaEmbedLoad
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.
<script type="text/javascript">
window.adaSettings = {
onAdaEmbedLoad: () => {
window.adaEmbed.subscribeEvent("ada:campaigns:shown", (data) => {
console.log("Message received from campaign with key:", data.campaignKey);
});
}
};
</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.
<head>
<!-- ... -->
<script type="text/javascript">
window.adaSettings = {
parentElement: document.getElementById("custom-iframe")
}
</script>
</head>
<body>
<!-- ... -->
<div id="custom-iframe"></div>
</body>
Chat will render immediately inside the
parentElement
provided. This means that the conversation will also get initialized. We do not recommend initializing Embed2 with theparentElement
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 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.
<script type="text/javascript">
window.adaSettings = {
sensitiveMetaFields: {
jwt_token: "xxxxx.yyyyy.zzzzz",
}
}
</script>
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.
window.adaSettings = {
zdChatterAuthCallback: (callback) => {
// Here you should make a request to get the fresh JWT token
const token = "token goes here";
callback(token)
}
};
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.
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
: ifignoreFrequency
istrue
, trigger conditions for Campaigns that have already been triggered within the configured frequency are also evaluated and may be triggered.ignoreStatus?: boolean
: ifignoreStatus
istrue
, trigger conditions for inactive and draft Campaigns are also evaluated and may be triggered.
This action requires the Ada Pro package.
getInfo
getInfo(): Promise<WindowInfo>;
Returns a WindowInfo
object containing information about the bot. See WindowInfo for more details.
window.adaEmbed.getInfo().then(function(windowInfo){
console.log("is the drawer open?");
console.log(windowInfo.isDrawerOpen ? "Yes": "No");
});
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
.
window.adaEmbed.reset({
greeting: "5e9481e296ac6c4467092be5"
});
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.
window.adaEmbed.setLanguage("en");
Before using setLanguage
:
-
You must turn languages on under Settings > Bot Setup > Multilingual on your Ada dashboard. See Multilingual 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.
window.adaEmbed.setMetaFields({
phone_number: "(123) 456-7890",
name: "Ada Lovelace"
});
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.
window.adaEmbed.setSensitiveMetaFields({
jwt_token: "xxxxx.yyyyy.zzzzz",
});
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
).
window.adaEmbed.start({
handle: "my-bot",
language: "fr",
mobileOverlay: true
});
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.
window.adaEmbed.subscribeEvent("ada:campaigns:shown", (data) => {
console.log("Message received from campaign with key:", data.campaignKey);
});
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, theeventKey
of the event that triggered the callback.
window.adaEmbed.subscribeEvent("ada:campaigns", (data, context) => {
const { eventKey } = context;
if (eventKey === "ada:campaigns:shown") {
console.log("Message received from campaign with key:", data.campaignKey);
}
if (eventKey === "ada:campaigns:opened") {
console.log("Chat opened after being shown campaign with key:", data.campaignKey);
}
if (eventKey === "ada:campaigns:engaged") {
console.log("Chatter engaged with campaign with key:", data.campaignKey);
}
});
subscribeEvent
returns a number subscriptionId
that you can use to unsubscribe later (see unsubscribeEvent).
window.adaEmbed.subscribeEvent("ada:end_conversation", (data, context) => {
console.log("The conversation has been ended by the user.");
console.log("Chatter ID: ", data.chatter_id);
console.log("Chat Data: ", data.event_data);
console.log("Chat Transcript: ", data.event_data.chatter_transcript);
});
It is strongly recommended that you place initial subscriptions to events in the onAdaEmbedLoad
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.
window.adaEmbed.subscribeEvent("ada:chat_frame_timeout", (data, context) => {
// Perform logic needed here when chat fails to load.
});
The following are the events that you can currently subscribe to.
Event key | Data | Description |
---|---|---|
ada:campaigns:shown | campaignKey The key of the campaign that triggered the received message. | Triggered when the chat application receives a message originating from a campaign. |
ada:campaigns:opened | campaignKey The key of the last campaign shown before chat was opened. | Triggered when chat is opened after a proactive campaign has been shown. |
ada:campaigns:engaged | campaignKey The key of the last campaign shown before the conversation was engaged. | Triggered when the chatter engages a conversation (that is, sends a message) after being shown a campaign in the same session. |
ada:end_conversation | chatter_id Contains the chat id for the chatter.event_data Contains neccessary chat information (chat start time, chat end time, chat messages). chatter_transcript Contains the transcript between the user and the bot. | Triggered when the chatter ends the chat by closing the chat window or selecting End Chat. |
ada:chat_frame_timeout | null | Triggers when the chat iframe has loaded, but the chat application does not confirm it is ready within 5 seconds. Used to create a fallback when chat fails to load. |
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");
The chat window must be opened at least once before this method can be used.
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.
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.
window.adaEmbed.trackEvent("Example_Event", 2, {
productId: "a1b2c3",
customerSegment: "premium"
});
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.
const subscriptionId = await window.adaEmbed.subscribeEvent("ada:campaigns:shown", (data) => {
console.log("Message received from campaign with key:", data.campaignKey);
});
window.adaEmbed.unsubscribeEvent(subscriptionId);
Type signatures
Embed2 actions commonly use the following type signatures.
CampaignParams
{
ignoreFrequency?: boolean
ignoreStatus?: boolean
}
FlatObject
{
[key: string]\: string | number | boolean | null
}
ResetParams
{
greeting?: string;
language?: string;
metaFields?: FlatObject;
sensitiveMetaFields?: FlatObject;
}
WindowInfo
{
hasActiveChatter: boolean;
hasClosedChat: boolean;
isChatOpen: boolean;
isDrawerOpen: boolean;
}