NAV

Introduction

Hello, and welcome to the Ada documentation hub! This is our place to store documentation on our publicly accessible APIs, libraries, and utilities.

Audience

This document is primarily intended for developers and individuals with some practical programming experience.

Upgrading From Embed1

If you are coming to Embed2 from Embed1, great! Upgrading couldn't be simpler. For basic setups, you most likely just need to upgrade you Embed script src from https://static.ada.support/embed.js to https://static.ada.support/embed2.js.

Although the Embed2 API is almost identical to Embed1, in some cases features have been removed or modified. You can find a comprehensive list of changes below.

Embed1 Feature Status Comments
authCallback Modified Renamed to zdChatterAuthCallback.
crossWindowPersistence Modified Simplified to accept a boolean instead of an object.
dragAndDrop Deprecated
mobileOverlay Deprecated
private Modified Renamed to privateMode.
styles Deprecated

Additionally, all actions have been modified to return Promises.

Embed2

Embed2 is a small JavaScript script that embeds your Ada Chat bot into your web page. It comes equipped with various settings and actions to tailor the end-user experience.

Embed2 Quick Start

1. Turn on your bot

The first step towards adding your Ada Chat Bot to your web page is to turn on the Web Chat integration in your Settings > Platforms page.

2. Approved domains

As a security precaution, your bot won't launch on a website domain that you haven't authorized. To authorize a domain, add it to the Approved Domains list on the Ada dashboard, under Settings > Bot Setup > Approved Domains.

See the Approved Domains guide to learn more.

3. Embed script

<head>
  ...
  <script
    id="__ada"
    data-handle="<YOUR-BOT-HANDLE>"
    src="https://static.ada.support/embed2.js"
  ></script>
</head>

Be sure to replace <YOUR-BOT-HANDLE> with your own bot handle. It's usually the name of your company.

Once you have your website all ready-to-go, find the page where you'd like to embed the Ada Chat bot. In most cases this will be an HTML file. Here you will need to paste the following into the <head> tag.

Loading a bot on a non-US cluster

If your bot is not on the US cluster, you can use data-domain in the script tag to choose the correct one.

If you are not sure which cluster your bot is on, please reach out to an Ada team member.

<head>
  ...
  <script
    id="__ada"
    data-domain="maple.ada" // e.g. eu.ada, att.ada etc
    data-handle="<YOUR-BOT-HANDLE>"
    src="https://static.ada.support/embed2.js"
  ></script>
</head>

4. That's it! 🎉

You should now see a small question mark button on the bottom right corner of your page. Clicking the button will toggle the Web Chat in and out of view.

You can see see a working example here.

Advanced Setup

In some situations, the quick setup above may be too simplistic. You may want to delay instantiation of Embed2 until a certain event, your application might be a Single-Page App and you need more control, or perhaps you want to set the bot language. Whatever the reason, Embed2 ships with additional features to help you get setup.

If you still require recommendations on how best to implement the Embed2 script, please reach out to an Ada team member. However, please note that all implementations are ultimately the responsiblity of your development team.

Ada Settings

<script>
  window.adaSettings = {
    ...
  }
</script>
...
<!-- Define the Embed script afterwards -->

Embed2 supports a number of configurable options which can be set through an adaSettings object you define on your window scope. Alternatively, settings can also be passed to the adaEmbed.start method (see Lazy Mode).

A full list of adaSettings options can be found in API Reference.

Lazy Mode

<script
  id="__ada"
  data-lazy
  data-handle="<YOUR-BOT-HANDLE>"
  src="https://static.ada.support/embed2.js"
></script>

Start Embed2 in your JS when you are ready to.

window.adaEmbed.start({
  handle: "my-bot",
  metaFields: {
    username: "Ada Lovelace",
    phone_number: "123-456-7890"
  },
  chatterTokenCallback: (chatter) => console.log(chatter)
});

Lazy mode can be configured to delay Embed2 instantiation. To put Embed2 in lazy mode, add the attribute data-lazy to the Embed2 script.

When you are ready to instantiate Embed2, call the start action. You can pass any settings you would normally set in window.adaSettings here.

Async

<script
  async
  id="__ada"
  data-handle="<YOUR-BOT-HANDLE>"
  src="https://static.ada.support/embed2.js"
></script>

Approach 1: Use the native script onload handler

<script
  async
  id="__ada"
  onload="window.adaEmbed.toggle()"
  data-handle="<YOUR-BOT-HANDLE>"
  src="https://static.ada.support/embed2.js"
></script>

Approach 2: Use the adaReadyCallback

window.adaSettings = {
  adaReadyCallback: () => {
    window.adaEmbed.toggle();
  }
};

Since HTML5, the async attribute has been available for HTML script elements. From MDN, it "allows the elimination of parser-blocking JavaScript where the browser would have to load and evaluate scripts before continuing to parse". It may be applied to the Embed2 script in order to improve load times of your page, however it does come with certain caveats.

If your bot implementation makes use of any actions from the global adaEmbed object, you must wait for the object to be added to your document. There are two common approaches for handling this situation.

Approach 1 involves using the native script onload handler. When the script has loaded, the load event will be triggered. It is safe to call adaEmbed actions from here.

Approach 2 involves using the adaReadyCallback, which you can set in window.adaSettings. Note that while in the examples provided toggle will work effectively the same way, adaReadyCallback is triggered after adaEmbed.start(...) has executed. Meanwhile, onload is simply triggered when the Embed2 script has been loaded.

RequireJS

<script>
  window.adaSettings = {
    handle: "<YOUR-BOT-HANDLE>"
  };
</script>

<script
  src="https://static.ada.support/embed2.js"
></script>

If you are using RequireJS as your module loader, you may encounter issues with the standard Embed2 setup. This is because RequireJS does not know how to interpret the id and data-handle attributes Ada uses. Instead of setting this attributes, you can just set handle in your window.adaSettings object.

If you experience additional errors be sure to check out the RequireJS Common Errors documentation.

Embed2 API Reference

Embed2 supports numerous settings and actions to help you customize the look and behaviour of your bot. They determine intrinsic properties like bot style and behaviour.

Settings are set on the window object as window.adaSettings = { ... }. Alternatively, they can be passed directly to adaEmbed.start({ ... }) for advanced configurations. The following is the full list of available settings:

adaReadyCallback

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

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.

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 will not need to change this value.

conversationEndCallback

conversationEndCallback?(callback: (event?: { [key]: string | object }) => void): void;

window.adaSettings = {
  conversationEndCallback: (event) => {
    // perform action after conversation has been ended by the chatter
  }
};

The conversationEndCallback can be used to specify a callback function to be called when a conversation has been ended by the chatter. The callback will receive an event object containing conversation metadata.

crossWindowPersistence

crossWindowPersistence?: boolean;

When set enables 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.

domain

domain?: string;

Can be used to change the subdomain. Unless directed by an Ada team member, you will not need to change this value.

greeting

greeting?: string;

This can be used to customize the greeting messages that new users 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. The ID can be found in the URL of the corresponding Answer in the dashboard.

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, this will prevent the default mask from appearing over top of your site's content when opened on desktop.

language

language?: string;

Takes in a language code to programatically set the bot language. Languages must first be turned on in the Settings > Multilingual page of your Ada dashboard.

lazy

lazy?: boolean;

When true, this will prevent the bot from loading until the adaEmbed.start(...) method is called.

metaFields

<script type="text/javascript">
  window.adaSettings = {
    metaFields: {
      phone_number: "(123) 456-7890",
      name: "Ada Lovelace"
    }
  }
</script>

metaFields?: FlatObject;

Used to pass meta information about a chatter. This can be useful for tracking information about your end users, as well as for personalizing their experience. For example, you may wish to track the phone_number and name for conversation attribution. Once set, this information can be accessed in the email attachment from Handoff Form submissions, or via the Chatter Info modal in the Conversations page of your Ada dashboard. Should you need to programatically change these values after bot setup, you can make use of the setMetaFields action.

onAdaEmbedLoad

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

Called when the embed script has been loaded, and before it is initialized. This is useful for subscribing to events (see subscribeEvent) - subscribing here ensures subscriptions are in place before events are triggered.

parentElement

<head>
  <!-- ... -->
  <script type="text/javascript">
    window.adaSettings = {
      parentElement: document.getElementById("custom-iframe")
    }
  </script>
</head>
<body>
  <!-- ... -->
  <div id="custom-iframe"></div>
</body>

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.

privateMode

privateMode?: boolean;

If set to true, this will put Web Chat into "Private" mode. This will cause Web Chat to forget conversation history on refresh. This is effectively the same as setting your Web Chat platform persistence to "Forget After Reload" in the Settings > Platforms page of your Ada dashboard. More information on persistence can be found here.

rolloutOverride

rolloutOverride?: number;

Can be used 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

<script type="text/javascript">
  window.adaSettings = {
    sensitiveMetaFields: {
      jwt_token: "xxxxx.yyyyy.zzzzz",
    }
  }
</script>

sensitiveMetaFields?: FlatObject;

Similar to metaFields except the values are not stored in the database and will be deleted after 24 hours.

testMode

testMode?: boolean;

Marks the chatter as a test user.

toggleCallback

toggleCallback?(isDrawerOpen: boolean): void;

Can be used to trigger side-effects when the Web Chat drawer is opened or closed.

zdChatterAuthCallback

zdChatterAuthCallback?(callback: (token: string) => void): void;

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

When called, the zdChatterAuthCallback can be used to request a JWT token from your API, and then have it passed to Ada. This allows for a shared trust between Ada and Zendesk, and in turn for verifiable chatter identity.

Embed2 Actions

Actions can be called from the global adaEmbed object. A list of the available actions is available below.

closeCampaign

This action requires the Ada Engage feature

closeCampaign(): Promise<void>;

Closes the currently-displayed campaign (does nothing if no campaign is currently displayed).

deleteHistory

deleteHistory(): Promise<void>;

Deletes the chatter used to fetch conversation logs for an end-user from storage. When a user opens a new Chat window a new chatter will be generated.

evaluateCampaignConditions

This action requires the Ada Engage feature

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 (if any) 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 may be helpful when testing your Campaign. The options are: - ignoreFrequency?: boolean: if ignoreFrequency is true, Campaigns that have already been triggered within the frequency configured on the Campaign will also have their trigger conditions evaluated and may be triggered. - ignoreStatus?: boolean: if ignoreStatus is true, inactive and draft Campaigns will also have their trigger conditions evaluated and may be triggered.

getInfo

getInfo(): Promise<WindowInfo>;

Returns a WindowInfo object containing information about the bot.

reset

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

reset(resetParams?: ResetParams): Promise<void>;

Creates a new chatter and refreshes the Chat window. reset can take an optional object allowing language, metaFields, sensitiveMetaFields, and greeting to be changed for the new chatter.

To prevent creating a new chatter (and maintain conversation history), resetChatHistory can be passed to the object with a value of false.

setMetaFields

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

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 methods may be useful.

setSensitiveMetaFields

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

setSensitiveMetaFields(fields: FlatObject): Promise<void>;

Same as setMetaFields except the values are not stored in the database and will be deleted after 24 hours.

start

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

start(adaSettings: StartOptions): Promise<void>;

Used to initialize Embed2 on your page. This action is triggered by default internally, so you will likely not need to call it directly unless you are using Embed2 is lazy mode, or have called stop and want to re-start Embed2.

StartOptions matches anything in Embed2 API Reference (e.g. adaReadyCallback).

stop

stop(): Promise<void>;

Removes Embed2 from your page.

subscribeEvent

subscribeEvent(eventKey: string, callback: (data: object, context: object) => void): Promise<number>

window.adaEmbed.subscribeEvent("ada:campaigns:shown", (data) => {
  console.log("Message received from campaign with key:", data.campaignKey);
});
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);
  }
});
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);
    });
window.adaEmbed.subscribeEvent("ada:chat_frame_timeout", (data, context) => {
  // Perform logic needed here when chat fails to load.
});

When certain events happen in Ada, events will be triggered. Each event consists of an event key and a data payload. Using subscribeEvent, you can define callbacks that get called when a specific event is triggered.

Callbacks will be triggered whenever an event starts with the eventKey provided to subscribeEvent. This allows subscribing 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 will be provided to each callback when it is called: data and context. data is specific to each event (see table below). context is an object with a single property eventKey, which is the event key of the event that triggered the callback to be called.

subscribeEvent returns a number subscriptionId which can be used to unsubscribe later (see unsubscribeEvent).

It is strongly recommended that initial subscriptions to events be placed in the onAdaEmbedLoad function. This ensures that the embed script has been loaded (so it is available to accept subscriptions), and that subscriptions happen before any events are triggered so that no events are missed.

The following is a list of the currently available events that can be subscribed to. More events may be added in the future.

Event key Data Description
ada:campaigns:shown campaignKey - the key of the campaign which triggered the received message Triggered when the chat application receives a message that originates 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 (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 (i.e. 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 selecting "End Chat" or "X".
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>;

Can be used to programatically open / close the Chat window. This method cannot be used with the parentElement option.

triggerCampaign

This action requires the Ada Engage feature

triggerCampaign(campaignKey: string, options: CampaignParams): Promise<void>;

Used to trigger the proactive Campaign with key campaignKey.

An optional second argument options can be passed. These options may be helpful when testing your Campaign. The options are: - ignoreFrequency?: boolean: if ignoreFrequency is true, the Campaign will be triggered even if it has already been triggered within the frequency configured on the Campaign. - ignoreStatus?: boolean: if ignoreStatus is true, the Campaign will be triggered even if it is inactive or in a draft state.

trackEvent

This action requires the Ada Engage feature

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

trackEvent(eventKey: string, value?: number, meta?: FlatObject)

Used to track an Event. The arguments to this function are: - eventKey: string: (required) the key of the Event to track. - value?: number: an optional value to assign to the Event. - meta?: FlatObject: an option object containing metadata corresponding to the Event. For example, it may be useful to track information such as currency, product group, customer segment, etc.

unsubscribeEvent

unsubscribeEvent(subscriptionId: number): void;

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

window.adaEmbed.unsubscribeEvent(subscriptionId);

This function can be used to remove subscriptions created with the subscribeEvent function above. It takes a single parameter subscriptionId, which is the id of the subscription to be removed.

Common Types

These type signatures are used in various actions.

CampaignParams

{ ignoreFrequency?: boolean ignoreStatus?: boolean }

FlatObject

{ [key: string]: string | number | boolean | null }

ResetParams

{ greeting?: string; language?: string; metaFields?: FlatObject; resetChatHistory?: boolean; sensitiveMetaFields?: FlatObject; }

WindowInfo

{ hasActiveChatter: boolean; hasClosedChat: boolean; isChatOpen: boolean; isDrawerOpen: boolean; }

FAQ

How do I setup Ada Chat for my mobile app?

Ada now has native support for both iOS and Android apps! Find out more about iOS here, and Android here.

How do I customize the look and feel of the Ada Chat button?

Ada supports multiple options for button configuration through the dashboard. Without any code, you can customize attributes such as the button colour, size, and icon.

How do I customize the look and feel of the Chat window?

Basic branding, including colours and icons, can be configured through the Ada dashboard.

Ada Embed is rendered as soon as the page loads. How can I delay rendering?

Embed2 features a useful data attribute called data-lazy. When defined on your script, Embed2 will not be triggered until you manually call adaEmbed.start(...). Alternatively, the lazy property can be passed to the window.adaSettings. See Advanced Setup for more information.

Versioning

The Embed script found above is versionless. This means that the latest stable features will be made available to you without any changes to your code.

Browser Support

Please see Ada Browser Compatibility.

iOS SDK

The Ada iOS SDK is a small framework that is used to embed your Ada Chat bot into your native iOS application.

iOS Installation

The Ada iOS SDK can be installed manually or using CocoaPods. The SDK supports iOS 10.x and up.

Option 1: Manual Integration

  1. Download the AdaEmbedFramework.framework.zip file from the latest release here.
  2. Right click on the project file in XCode, then click "Add Files to MyProjectName". Ensure that the Copy groups option is selected.
  3. Ensure your Deployment Target is set to 10.0, which is the minimum iOS version that the Ada iOS SDK is compatible with.
  4. In the project settings under General, link the AdaEmbedFramework.framework under the Embedded Binaries section. You can do this by dragging the framework from the left side list in the Embedded Binaries list.

Option 2: CocoaPods

# Podfile
platform :ios, '10.0'

target 'MyApp' do
  use_frameworks!

  # Pods for MyApp
  pod "AdaEmbedFramework", "~>1.3.0"

end

Be sure to get the latest version at https://cocoapods.org/pods/AdaEmbedFramework.

The AdaEmbedFramework CocoaPod is public, however use of the Chat interface is gated. To gain access please reach out to an Ada Account Manager.

  1. Add the AdaEmbedFramework to your Podfile.

  2. Install the pod using:

pod install

iOS Quick Start

import AdaEmbedFramework

# ...

lazy var adaFramework = AdaWebHost(handle: "ada-example")

Once you have installed the Ada iOS SDK, you are ready to use it in your app! To start, import AdaEmbedFramework into your controller. Then, create an instance of the AdaWebHost.

The lazy property prevents AdaWebHost from initializing until the property is used. Use of this property may help to prevent unwanted chatters from being created in the background.

Please note "ada-example" is being used for demonstration purposes. Be sure to sure modify "handle", as well as any other values as needed for your bot.

Finally, launch Ada using any of the 3 opening methods: launchModalWebSupport, launchNavWebSupport, or launchInjectingWebSupport.

iOS API Reference

Settings

AdaWebHost can take various input parameters to customize the behaviour of your Chat bot.

appScheme

appScheme: String = ""

Can be used to pass the scheme name of the host app. This allows for more robust handling of universal links.

cluster

cluster: String = ""

Specifies the Kubernetes cluster to be used. Unless directed by an Ada team member, you will not need to change this value.

greeting

greeting: String = ""

This can be used to customize the greeting messages that new users see. This is useful for setting view-specific greetings across your app. The greeting should correspond to the ID of the Answer you would like to use. The ID can be found in the URL of the corresponding Answer in the dashboard.

handle

handle: String

The handle for your bot. This is a required field.

language

language: String = ""

Takes in a language code to programatically set the bot language. Languages must first be turned on in the Settings > Multilingual page of your Ada dashboard.

metaFields

lazy var adaFramework = AdaWebHost(handle: "ada-example", metafields: ["tier": "pro"])

metafields: [String: String]? = [:]

Used to pass meta information about a Chatter. This can be useful for tracking information about your end users, as well as for personalizing their experience. For example, you may wish to track the phone_number and name for conversation attribution. Once set, this information can be accessed in the email attachment from Handoff Form submissions, or via the Chatter modal in the Conversations page of your Ada dashboard. Should you need to programatically change these values after bot setup, you can make use of the setMetaFields method below.

sensitiveMetafields

sensitiveMetafields: [String: String]? = [:]

Used to pass sensitive meta information about a Chatter. These work similar to regular metafields but provide an added layer or security. Should you need to programatically change these values after bot setup, you can make use of the setSensitiveMetafields method below.

openWebLinksInSafari

openWebLinksInSafari: Bool = false

External web links now open by default in-app via the SFSafariViewController. To open external links in the Safari browser, pass openWebLinksInSafari: true to AdaWebHost.

zdChatterAuthCallback

zdChatterAuthCallback: ((((_ token: String) -> Void)) -> Void)? = nil

lazy var adaFramework = AdaWebHost(handle: "nic", zendeskAuthCallback: { callback in
    // Request JWT from your API
    // Then...
    callback("your.JWT")
})

When called, the zdChatterAuthCallback can be used to request a JWT token from your API, and then have it passed to Ada. This allows for a shared trust between Ada and Zendesk, and in turn for verifiable chatter identity.

iOS Actions

deleteHistory

deleteHistory()

Deletes the chatter used to fetch conversation logs for an end-user from storage. When a user opens a new Chat window a new chatter will be generated.

launchInjectingWebSupport

adaFramework.launchInjectingWebSupport(into: injectingView)

launchInjectingWebSupport(into view: UIView)

Launches Ada Chat into a specified subview.

launchModalWebSupport

adaFramework.launchModalWebSupport(from: self)

launchModalWebSupport(from viewController: UIViewController)

Launches Ada Chat in a modal view overtop your current view.

launchNavWebSupport

adaFramework.launchNavWebSupport(from: navigationController)

launchNavWebSupport(from navController: UINavigationController)

Pushes a view containing Ada Chat to the top of your navigational stack.

reset

reset()

Can be used to create a new chatter and refresh the Chat window.

setMetaFields

adaFramework.setMetaFields([
    "firstName": "Jane",
    "lastName": "Doe",
    "tier": "pro"
])

setMetaFields(_ fields: [String: Any])

Used to set meta data for a chatter after instantiation. This is useful if you need to update user data after Ada Chat has already launched.

setSensitiveMetaFields

adaFramework.setSensitiveMetaFields([
  "token": "your_jwt_token"
])

setSensitiveMetaFields(_ fields: [String: Any])

Used to set sensitive meta data for a chatter after instantiation. This works similar to setMetaFields and is useful for more storing more private and sensitive information.

Android SDK

The Ada Android SDK is a small framework that is used to embed your Ada Chat bot into your native Android application.

Android Installation

The Ada Android SDK can be installed manually or using Gradle.

Manual

The Ada Android SDK can be installed manually from the .aar file. Files can be found here.

// build.gradle
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
}

To install the library you need to save the .aar file under your app module libs folder, for example MyAwesomeProject/app/libs, and include *.aar in application level build.gradle file.

After that, synchronize the project.

You can also import a file using Android Studio. To do this, go to File -> New -> New Module. In the window select Import .JAR/.AAR Package and click Next. After that, specify the path to the .aar file and the module name, and click Finish.

// build.gradle
implementation project(':new_module_name')

Finally, define the implementation for the new local library module.

Gradle

// build.gradle
allprojects {
    repositories {
        maven {
            url "https://gitlab.com/api/v4/projects/25892134/packages/maven"
        }
    }
}

The Ada Android SDK can be installed using Gradle from the Ada Support Gitlab repository.

To integrate the SDK, first add the following code to the project level build.gradle file.

If your project has artifacts within the AndroidX namespace, use:

implementation 'support.ada.embed:android-sdk-appcompat:1.3.9'

If your project uses Android Support Library, use:

implementation 'support.ada.embed:android-sdk-appcompat-legacy:1.3.9'

Be sure to get the latest version at https://gitlab.com/adasupport/androidsdk/-/packages.

Next, add the dependency to the application level build.gradle.

Android Quick Start

After installing the SDK, you can start Ada chat in several ways.

XML

<!-- XML -->
<support.ada.embed.widget.AdaEmbedView
        android:id="@+id/ada_chat_frame"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        app:ada_handle="ada-example" />

Please note "ada-example" is being used for demonstration purposes. Be sure to modify the handle, as well as any other values as needed for your bot.

The simplest way to start Ada Chat is via XML.

To display the view, the ada_handle parameter is required. If you specify it as an attribute, the chat will be displayed immediately upon attachment to the parent view. If it is not specified, then you can do it later programmatically using the method initialize(settings: AdaEmbedView.Settings).

// Delayed initialization
val adaView = findViewById(R.id.ada_chat_frame)

adaSettings = AdaEmbedView.Settings.Builder("ada-example")
    .build()
adaView.initialize(adaSettings)

Programmatically

val adaView = AdaEmbedView(getContext())

val adaSettings = AdaEmbedView.Settings.Builder("ada-example")
    .build()
adaView.initialize(adaSettings)

To programmatically create the chat frame, you need to create a view object and pass context to the constructor.

After this, the view will be created, but will not be initialized. To do this call initialize(settings: AdaEmbedView.Settings), passing the settings object as an argument.

Finally, to display the newly created chat frame on screen, simply add the view to your container.

Dialog

val dialog = AdaEmbedDialog()
 adaDialog.arguments = Bundle().apply {
    putParcelable(AdaEmbedDialog.ARGUMENT_SETTINGS, settings)
 }
dialog.show(supportFragmentManager, AdaEmbedDialog.TAG)

Note that TAG is a simple class name, you can use any value you want.

To display a separate chat window on top of the current window, you can use AdaEmbedDialog.

First, create a dialog object and pass the settings to its arguments using a constant AdaEmbedDialog.ARGUMENT_SETTINGS.

Then show it using the native Android show method.

Activity

val intent = Intent(context, AdaEmbedActivity::class.java)
intent.putExtra(AdaEmbedActivity.EXTRA_SETTINGS, settings)
context.startActivity(intent)

Note that you can use "AdaEmbedActivity" as a regular Android activity. For example, flags and actions can be added.

The SDK allows you to open the chat window in a separate window attached to the app navigation. For this you need to use AdaEmbedActivity.

Create an Intent and put the settings in it with the key AdaEmbedActiviti.EXTRA_SETTINGS and run the activity.

Send Files

adaView.filePickerCallback = { filePickerCallback ->
    filePickerCallback.onFileTaken(someUri)
    true
}

When using Ada Glass (for Zendesk live agent support), end users sometimes need to upload files. AdaEmbedActivity and AdaEmbedDialog already have this functionality, but if you work directly with AdaEmbedView you have to handle it yourself.

To do this, you need to setup a callback to AdaEmbedView. This callback will be fired when a user requests to attach a file. When you get the URI you can invoke filePickerCallback.onFileTaken(someUri); it will signal to AdaEmbedView that the file is ready to attach. It's also possible to pass null, which will cancel the request.

This operation doesn't require you to pass the file URI to callback immediately. You can save filePickerCallback and invoke the callback later (eg. take URI via file picker).

To notify AdaEmbedView that you are going to handle file attach you should return true.

Third-Party Cookies

app:ada_accept_third_party_cookies = "true"

The SDK has support for third-party cookies. Note that apps targeting Build.VERSION_CODES.KITKAT and lower already allow third-party cookies by default.

Android API Reference

Settings

<!-- Example 1: XML -->
<support.ada.embed.widget.AdaEmbedView
        android:id="@+id/ada_chat_frame"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        app:ada_handle="ada-example"
        app:ada_cluster="ca"
        app:ada_language="en"
        app:ada_handle="ada-example"
        app:ada_greetings="5c59aaabd8269e0339979014"/>
//Example 2: Kotlin
val adaSettings = AdaEmbedView.Settings.Builder("ada-example")
    .cluster("ca")
    .greetings("5c59aaabd8269e0339979014")
    .language("en")
    .metaFields(
        AdaEmbedView.MetaFields.Builder()
                .setField("name", "John")
                .setField("age", 20)
                .setField("authorized", true)
    )
    .sensitiveMetaFields(
        AdaEmbedView.MetaFields.Builder()
                .setField("top", "secret")
                .setField("id", 20)
                .setField("isUser", true)
    )
    .build()

Using the SDK, you can configure the initial chat settings for greater customization. Settings can be configured for XML, or programmatically using theAdaEmbedView.Settings class.

cluster

Specifies the Kubernetes cluster to be used. Unless directed by an Ada team member, you will not need to change this value.

greeting

This can be used to customize the greeting messages that new users see. This is useful for setting view-specific greetings across your app. The greeting should correspond to the ID of the Answer you would like to use. The ID can be found in the URL of the corresponding Answer in the dashboard.

handle

The handle for your bot. This is a required field.

language

Takes in a language code to programmatically set the bot language. Languages must first be turned on in the Settings > Multilingual page of your Ada dashboard.

metaFields

Used to pass meta information about a Chatter. This can be useful for tracking information about your end users, as well as for personalizing their experience. For example, you may wish to track the phone_number and name for conversation attribution. Once set, this information can be accessed in the email attachment from Handoff Form submissions, or via the Chatter modal in the Conversations page of your Ada dashboard.

You can also set "meta fields" using XML. For this, you need to create a JSON file in the res/raw directory, and set the reference to the view declaration:

sensitiveMetaFields

Similar to metaFields except the values are not stored in the database and will be deleted after 24 hours.

zdChatterAuthCallback

When using AdaEmbedView

adaView.zdChatterAuthCallback = {
    getToken() // this functions returns String
}

When using AdaEmbedDialog

val adaDialog = AdaEmbedDialog()
adaDialog.zdChatterAuthCallback = {
    getToken() // this functions returns String
}

When called, the zdChatterAuthCallback will request a JWT token (probably generated by your API), and then have it passed to Ada. This allows for validation between your App and Ada that the user is authenticated, and in turn between Ada and Zendesk for verifiable chatter identity.

To implement, zdChatterAuthCallback must be defined on adaView, or adaDialog. If the SDK requests a JWT token, this callback will be fired.

Android Actions

deleteHistory

adaView.deleteHistory()

Deletes the chatter used to fetch conversation logs for an end-user from storage. When a user opens a new Chat window, a new chatter will be generated.

To do this you need to call deleteHistory() in your AdaEmbedView instance.

reset

Creates a new chatter and refreshes the Chat window. Reset can take an optional params: language, metaFields, and greeting to be changed for the new chatter.

To prevent creating a new chatter (and maintain conversation history), param resetChatHistory can be passed with a value of false.

To do this you need to call reset() in your AdaEmbedView instance: kotlin adaView.reset() Or with optional params:

val metaFields = AdaEmbedView.MetaFields.Builder()
                .setField("name", "John")
                .setField("age", 20)
                .setField("authorized", true))
val sensitiveMetaFields = AdaEmbedView.MetaFields.Builder()
                .setField("name", "John")
                .setField("age", 20)
                .setField("authorized", true))
adaView.reset(language = "fr", metaFields = metaFields, sensitiveMetaFields = sensitiveMetaFields)

setMetaFields

val metaFields = AdaEmbedView.MetaFields.Builder()
                .setField("name", "John")
                .setField("age", 20)
                .setField("authorized", true))
adaView.setMetaFields(metaFields)

The SDK allows you to change your meta fields while the chat frame is displayed.

To do this you need to call setMetaFields() in your AdaEmbedView instance and pass your new meta fields as an argument:

setSensitiveMetaFields

val sensitiveMetaFields = AdaEmbedView.MetaFields.Builder()
                .setField("name", "John")
                .setField("age", 20)
                .setField("authorized", true))
adaView.setSensitiveMetaFields(sensitiveMetaFields)

The SDK allows you to change your sensitive meta fields while the chat frame is displayed.

To do this you need to call setSensitiveMetaFields() in your AdaEmbedView instance and pass your new sensitive meta fields as an argument:

AdaEmbedActivity & AdaEmbedDialog

// AdaEmbedActivity
class MyCustomActivity : AdaEmbedActivity(){
    override fun onResume() {
        super.onResume()
        val adaView = getAdaView()
        adaView.setMetaFields(
            AdaEmbedView.MetaFields.Builder()
                .setField("name", "John")
                .setField("age", 20)
                .setField("authorized", true))
        adaView.setSensitiveMetaFields(
            AdaEmbedView.MetaFields.Builder()
                .setField("top", "secret")
                .setField("id", 20)
                .setField("isUser", true))
        adaView.deleteHistory()
        adaView.reset()
    }
}

To call actions in the AdaEmbedActivity, you first need to create your own activity that inherits AdaEmbedActivity. Then using the getAdaView() you can obtain the AdaEmbedView instance:

// AdaEmbedDialog
val adaDialog = supportFragmentManager.findFragmentByTag(AdaEmbedDialog.TAG) as AdaEmbedDialog
adaDialog.setMetaFields(
            AdaEmbedView.MetaFields.Builder()
                .setField("name", "John")
                .setField("age", 20)
                .setField("authorized", true))
adaDialog.setSensitiveMetaFields(
            AdaEmbedView.MetaFields.Builder()
                .setField("top", "secret")
                .setField("id", 20)
                .setField("isUser", true))
adaDialog.deleteHistory()
adaDialog.reset()

To call actions in the AdaEmbedDialog, you can obtain AdaEmbedDialog instance from FragmentManager:

React Native SDK

The Ada React Native SDK is a small framework that is used to embed your Ada Chat bot into your React Native application.

The Ada React Native SDK is based on react-native-webview. Before you can use the SDK, you will need to follow the react-native-webview "Getting Started Guide".

When you've configured react-native-webview, simply install the Ada React Native SDK via NPM.

When you are testing/developing locally please ensure you add http://localhost:8081/ temporarily to your Approved Domains. Without doing this the bot will be blocked by the Content Security Policy.

Breaking Change in version 2.2.0

As of version 2.2.0 of @ada-support/react-native-sdk we require a native module to be imported for iOS to enable the ability to download transcripts. Whether or not you have this feature enabled, the code depends on importing these native modules. Please follow steps 2,3 and 4 in Installation to update your existing configuration after you have updated your @ada-support/react-native-sdk to version 2.2.0 or greater.

Installation

1. Install Ada React Native SDK via NPM

a) With npm

npm install --save @ada-support/react-native-sdk

b) With yarn

yarn add @ada-support/react-native-sdk

2. Update your iOS Podfile to include the following import.

require_relative '../node_modules/@ada-support/react-native-sdk/react_native_pods'

3. Update your iOS Podfile to include the following piece of code.

This will import any needed native modules that we include in the React Native SDK.

use_ada!()

4. Run pod install in your app to install the needed native modules.

# Example Podfile
require_relative '../node_modules/react-native/scripts/react_native_pods'
require_relative '../node_modules/@react-native-community/cli-platform-ios/native_modules'
require_relative '../node_modules/@ada-support/react-native-sdk/react_native_pods'

platform :ios, '11.0'

target 'example' do
  config = use_native_modules!

  use_react_native!(
    :path => config[:reactNativePath],
    # to enable hermes on iOS, change `false` to `true` and then install pods
    :hermes_enabled => false
  )

  use_ada!()

  target 'exampleTests' do
    inherit! :complete
    # Pods for testing
  end

  # Enables Flipper.
  #
  # Note that if you have use_frameworks! enabled, Flipper will not work and
  # you should disable the next line.
  use_flipper!()

  post_install do |installer|
    react_native_post_install(installer)
  end
end

React Native Quick Start

import AdaEmbedView from '@ada-support/react-native-sdk';
// ...

class MyComponent extends React.Component {
  render() {
    return <AdaEmbedView handle="ada-example"/>;
  }
}

Once you have installed the Ada React Native SDK, you are ready to use it in your app! Simply import the AdaEmbedView component, then render it. Note that you must pass a valid handle for the Chat window to work.

File Permissions

Some functionality in the Ada Chat bot will not work unless permissions are explicitly given.

React Native iOS Permissions

<!-- Photo capture -->
<key>NSCameraUsageDescription</key>
<string>Take pictures for certain activities</string>

<!-- Gallery selection -->
<key>NSPhotoLibraryUsageDescription</key>
<string>Select pictures for certain activities</string>

<!-- Video recording -->
<key>NSMicrophoneUsageDescription</key>
<string>Need microphone access for recording videos</string>

For iOS, all you need to do is specify the permissions in your ios/[project]/Info.plist file.

React Native Android Permissions

<manifest ...>
  ...
  <!-- this is required only for Android 4.1-5.1 (api 16-22)  -->
  <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
  ...
</manifest>

For Android, add permissions in AndroidManifest.xml.

React Native API Reference

Props

AdaEmbedView can take various props to customize the behaviour of your Chat bot.

cluster

cluster?: string;

Specifies the Kubernetes cluster to be used. Unless directed by an Ada team member, you will not need to change this value.

greeting

greeting?: string;

This can be used to customize the greeting messages that new users see. This is useful for setting view-specific greetings across your app. The greeting should correspond to the ID of the Answer you would like to use. The ID can be found in the URL of the corresponding Answer in the dashboard.

handle

handle: string;

The handle for your bot. This is a required field.

language

language?: string;

Takes in a language code to programatically set the bot language. Languages must first be turned on in the Settings > Multilingual page of your Ada dashboard.

metaFields

metaFields={{
  name: "Some name",
  age: 30
}}

metaFields?: object;

Used to pass meta information about a chatter. This can be useful for tracking information about your end users, as well as for personalizing their experience. For example, you may wish to track the phone_number and name for conversation attribution. Once set, this information can be accessed in the email attachment from Handoff Form submissions, or via the Chatter modal in the Conversations page of your Ada dashboard. Should you need to programatically change these values after bot setup, you can make use of the setMetaFields method below.

thirdPartyCookiesEnabled (Android)

thirdPartyCookiesEnabled?: boolean;

The thirdPartyCookies prop can be set to enable third-party cookies in the AdaEmbedView. This feature is only available in Android. The default value is false.

zdChatterAuthCallback

zdChatterAuthCallback?(callback: (token: string) => void): void;

zdChatterAuthCallback={callback => {
  const token = getTokenFromAPI(); // Get a fresh JWT token from your API
  callback(token);
}}

The zdChatterAuthCallback can be used to request a JWT token from your API, and then have it passed to Ada. This allows for a shared trust between Ada and Zendesk, and in turn for verifiable chatter identity.

endConversationCallback

endConversationCallback?(callback: (event?: { [key]: string | object }) => void): void;

endConversationCallback={(event) => {
  // perform action after conversation has been ended by the chatter
}}

The endConversationCallback can be used to specify a callback function to be called when a conversation has been ended by the chatter. The callback will receive an event object containing conversation metadata.

React Native Actions

import AdaEmbedView from '@ada-support/react-native-sdk';
// ...

class MyComponent extends React.Component {
  render() {
    return <AdaEmbedView
            handle="ada-example"
            ref={ref => (this.adaEmbedView = ref)}/>;
  }
}

Actions can be called directly from the AdaEmbedView ref. This allows you to modify Ada Chat without using state/props to trigger a re-render of the entire subtree.

deleteHistory

this.adaEmbedView.deleteHistory();

Deletes the chatter used to fetch conversation logs for an end-user from storage. When a user opens a new Chat window, a new chatter will be generated.

reset

this.adaEmbedView.reset();

// With options
this.adaEmbedView.reset({
  metaFields: {
    name: "Some name",
    age: 30
  },
  resetChatHistory: false
});

Creates a new chatter and refreshes the Chat window. reset can take an optional object allowing language, metaFields, and greeting to be changed for the new chatter.

To prevent creating a new chatter (and maintain conversation history), resetChatHistory can be passed to the object with a value of false.

setMetaFields

this.adaEmbedView.setMetaFields({
  name: "Some name",
  age: 30
});

Used to set meta data for a chatter after instantiation. This is useful if you need to update user data after Ada Chat has already launched.

Push Notifications (beta)

Ada currently supports sending push notifications via Firebase Cloud Messaging (FCM) or Apple Push Notification service (APNs).

If your application or website is already capable of sending web/push notifications, it is likely that there are associated FCM and/or APNs credentials. Otherwise, you may need to discuss obtaining these with your development team.

FCM and/or APNs credentials are required in order for Ada to send web/push notifications on your behalf. Notifications will only be sent to chatters who have opted-in. You can view the types of notifications that will be sent here.

Push notification prompt in chat window

Learn more about Firebase Cloud Messaging

Learn more about Apple Push Notification service

Adding FCM and APNs credentials

The credentials can be added in your dashboard under Settings > Bot Setup > Mobile Push Notifications These credentials will be used to send notifications to chatters' devices on your behalf.

Push notification settings page in the Ada dashboard

Notification Triggers

a web notification

Notifications will only be sent to chatters who have opted-in.

The following events will trigger a notification:

Web Setup

Browser Support

The table below shows the mobile and desktop browser support. The number in parentheses is the lowest version supported by the FCM client.

Chrome (v.50+) Firefox (v.44+) Safari Edge (v.42+) IE11
Yes Yes No Yes No

Registering a chatter's device

In order for Ada to send web notifications to a chatter on your behalf, we need a device token to identify the chatter. The device token behaves like an address that FCM can deliver notifications to.

This device token is not used by Ada until the chatter opts-in to receive notifications on their device.

After a chatter opts-in, they will receive notifications on the registered device when any of the notification triggers occur.

To send the device token to Ada, your FCM client will need to be updated similar to the code snippet.

Click here for more information about accessing the device token.

import { getMessaging, getToken } from "firebase/messaging";

getToken(getMessaging, { vapidKey: '<YOUR_PUBLIC_VAPID_KEY_HERE>' }).then((currentToken) => {
  if (currentToken) {
    // add this code to send the device token to Ada
    adaEmbed.setDeviceToken(currentToken);
  }
})

Customizing the notification

The FCM client will receive the data required to create the notification such as the title, body and icon. More information about how to customize the notification can be found here.

Example customization code

The code snippet (link to documentation) shows the code that is executed in the FCM client when a notification from Ada is pushed to the registered chatter.

The chatter's browser will listen for the notification and will combine the notification title and body data from Ada with your customizations.

import { getMessaging } from "firebase/messaging";
import { onBackgroundMessage } from "firebase/messaging/sw";

const messaging = getMessaging();
onBackgroundMessage(messaging, (payload) => {
  // Customize notification here
  const { notification, data } = payload;
  const notificationTitle = notification.title;

  const notificationOptions = {
    body: notification.body,
    icon: 'https://your-site.com/your-logo.png'
    data,
  };

  self.registration.showNotification(notificationTitle, notificationOptions);
});

Handling the opening of a browser notification

The FCM client provides the ability to customize what happens when a chatter interacts with a browser notification.

The typical behaviour is for the browser to open the tab with the chat window embedded on it. This allows the chatter to pick up where they left off.

The code snippet shows how you can customize the behaviour.

All that is required is a notificationclick event listener and a couple conditions to make sure that the notification received by the browser is from Ada.

When the notification is from Ada, we would need to notify the page with the bot embedded on it using the postMessage function. This way, we can immediately open the bot when the notification is clicked.

// firebase-messaging-sw.js
self.addEventListener("notificationclick", (event) => {
  const { notification } = event;
  const { data } = notification;

  // check if the notification is from Ada
  const isNotificationFromAda = data["gcm.notification.source"].toLowerCase() === "ada";

  const handleNotificationClick = async () => {
    notification.close();

    if (isNotificationFromAda) {
      const [openedClientTab] = await clients.matchAll({
        includeUncontrolled: true,
        type: "window",
        url: data.initialUrl
      });

      if (openedClientTab) {
        // let the embedded bot know that the notification has been clicked
        openedClientTab.postMessage({ "type": "ada:web_notification:click" });

        // switch to the tab/window
        return openedClientTab.focus();
      } else {
        // returns the chatter to your site if the tab had been closed
        const newClientTab = await clients.openWindow(data.initialUrl);
        newClientTab.postMessage({ "type": "ada:web_notification:click" });
        return Promise.resolve();
      }
    }
  };

  event.waitUntil(handleNotificationClick());
});

iOS SDK Setup

Registering a chatter's device

In order for Ada to send iOS push notifications to a chatter on your behalf, we need a device token to identify the chatter. The device token behaves like an address that APNs can deliver notifications to.

To send the device token to Ada, your APNs client will need to be updated similar to the code snippet.

Click here for more information about accessing the device token.

//Option 1
AdaWebHost(...otherOptions, deviceToken: "<YOUR_DEVICE_TOKEN>")


//Option 2
let adaFramework = AdaWebHost(...otherOptions, deviceToken: "<YOUR_DEVICE_TOKEN>")

Android SDK Setup

Registering a chatter's device

In order for Ada to send Android push notifications to a chatter on your behalf, we need a device token to identify the chatter. The device token behaves like an address that FCM can deliver notifications to.

To send the device token to Ada, your FCM client will need to be updated similar to the code snippet.

Click here for more information about accessing the device token.

And then finally in your code, you can pass the device token as part of the AdaSettings.


//Option 1
return settingsBuilder
            // otherOptions
            .deviceToken("<YOUR_DEVICE_TOKEN>")
            .build()


//Option 2
val adaDialog = AdaEmbedDialog()
//your business logic
//later when you obtain a new device token
adaDialog.setDeviceToken("<YOUR_DEVICE_TOKEN>")

React Native SDK Setup

Registering a chatter's device

In order for Ada to send Android or iOS push notifications to a chatter on your behalf, we need a device token to identify the chatter. The device token behaves like an address that FCM can deliver notifications to.

To send the device token to Ada, your FCM client will need to be updated similar to the code snippet.

Click here for more information about accessing the device token on Android.

Click here for more information about accessing the device token on iOS.

And then finally in your code, you can pass the device token as part of the AdaSettings.

//your business logic
//later when you obtain a new FCM device token
this.adaEmbedView.setDeviceToken("<YOUR_DEVICE_TOKEN>");

SMS Notifications (beta)

phone number input for sms notifications

Chatters have the option to be notified by either push notifications or SMS.

Chatters who have provided a phone number will only receive an SMS when any of the notification triggers occur.

When a chatter receives an SMS, they will be provided a link that will return them to the page where they previously interacted with your bot.

Proactive SMS API

The Proactive SMS feature allows you to start personalized two-way conversations using Short Message Service (SMS) messages. These automated interactions are based on campaigns designed in the Ada dashboard, which you can trigger using the Proactive SMS API. With this API, you can use events from external systems to initiate real-time notifications, such as:

Example

When you send the request to trigger a campaign, you’ll include the phone number of your recipient, along with any metadata that you want to use to personalize your interaction with the chatter. Each piece of metadata becomes a variable that you can use throughout a conversation, by including it in the answers within your campaign.

Getting Started

To use the Proactive SMS API you need to:

Before you begin, configure your Sunshine Conversations integration, and enable the Twilio SMS channel within that integration (see Ada and Channels and Integrate Sunshine Conversations).

Authentication

To connect with the Proactive SMS API, you need an access token that you’ll include in the header of your requests.

  1. In the Ada dashboard, go to Settings > Integrations > API Integrations > Proactive SMS API.
  2. Click Configure.
  3. Copy the API Access Token. Keep it in a safe place, as you won’t be able to access it again.

If you misplace your token, click the Generate a new Access Token button to get a new one. When you do this, it invalidates the previous token.

Proactive SMS API Reference

Trigger an SMS Campaign

POST /campaigns/sms/trigger/

Connect to the host with the following address and base path, where {bot-name} is the name of your bot:

https://{bot-name}.ada.support/api/campaigns/sms/trigger

You can also copy this address directly from your dashboard, in the Campaign Triggers section of your SMS campaign.

## Trigger an SMS Campaign
curl -X "POST" "https://my-bot.ada.support/api/campaigns/sms/trigger" \
     -H 'Authorization: Bearer 2926a1304ce6b5ff29c1e7ed9b0bcee6' \
     -H 'Content-Type: application/json' \
     -d $'{
  "campaign_key": "renew_subscriptions",
  "language": "en",
  "recipient": {
      "meta_fields": {
        "phone_number": "4165551234",
        "first_name": "Sam"
      }
    }
}

Response

A 200 - OK response means that Ada has triggered the campaign and sent the messages to Twilio/SunCo. It does not account for any issues that might impact the messages once they leave the Ada system.

Header parameters

Use these parameters in the header.

Parameter Description Required? Type
Authorization Use the access token you generated above, in the format: Bearer <key>.
Example
Bearer 2926a1304ce6b5ff29c1e7ed9b0bcee6
Yes string

Body parameters

Use these parameters in the body of your request.

Parameter Description Required? Type
campaign_key Copy the campaign_key from your Ada dashboard, under Build > Campaigns, in the Campaign Key column. Yes string
language Type an ISO 639-1 language code as the value. For example, “en” for English. Defaults to the bot’s default language if not specified. Yes string
recipient Object containing the phone number for the recipient, and any metadata fields that you want to use in the interaction (more details below). There can only be one recipient per API call. Use the Send to a list option in the dashboard to send SMS messages to multiple recipients at a time. Yes object
meta_fields Use these fields to bring in data from another system. You can use this information to personalize the SMS interaction for your chatter. For example, you might want to include a chatter’s name, email address, or an order number. You must include a phone number as a meta field (more details below). Yes string
phone_number Include the recipient’s phone number as a meta field. The SMS message will be sent to this number. Yes string

Example

"recipient": { "meta_fields": { "phone_number": "4165551234", "first_name": "Sam", "last_name": "Zhang", "email": "sam.zhang@example.com", "latest_order": "12345" } }

Status Messages

Code Meaning
200 - OK Ada has triggered the campaign and sent the messages to Twilio/SunCo. A 200 status reflects that specific action, and cannot account for any issues that might impact the messages once they leave the Ada system.
400 - Bad request There’s something wrong with the query. Check your request and try again.
500 - Internal server error There was an issue on the server.

Proactive SMS API Changelog

Date Description
2022.04.01 Initial version.

Data Export API

Overview

Welcome to The Data Export API. This API provides authenticated access to your conversation and message data that you can export into your own data warehouse.

Use cases

The Data Export API is designed according to REST principles. The API accepts JSON in request bodies and will respond with a list of conversation/message objects, depending on which endpoint you’re querying.

What you’ll need to get started

Access to the Data Export API on your account

To get started with the Data Export API, you’ll need to speak with your account manager to have it added to your contract with Ada.

Data Export API Trial

A 30 day trial for Data API is available (feature flag: data_api_trial). The trial will begin once the first API access token is generated. Any regenerated API access tokens will have the same expiration date as the first API access token. Migrating to a paid Data Export API feature will require regenerating a new API access token to remove the initial expiration date.

API authentication tokens

In order to keep your data safe, all requests to the Data Export API must be authenticated.

Please request your account manager to enable the feature flag data_api for your bot to enable Data API access and self-serve authentication key generation modal for Admin and Owner level users to generate authentication keys.

Self-serve Authentication Token Generation

We offer HTTPS authentication via an API access token. Once logged into Ada, any user with Admin and Owner permissions can generate an authentication token.

Follow the steps below to create an authentication token:

Each account has one active token at a time. Put the token at the Authorization header of your request.

  1. Navigate to Settings → Integrations → API Integrations → Data Export API. Click Configure.

  2. A modal will pop up. Click Generate a new Access Token.

  3. The token is created, click the Copy button to copy the authentication token and store it in a secure place. The access token will be shown once at the time of generation. The next time you log in, the token will not be accessible through the console.

You now can use this Bearer token as the authorization header to access Data API, following this format:

Headers

Key Value
Authorization Bearer <your_api_token>

Authentication Token Regeneration

If you have lost the token or need to generate a new token, you will need to regenerate it via the console. We currently support one Access Token at a time; regeneration means a new token is issued and immediately invalidates the prior token.

Follow the steps below to regenerate a new token:

  1. Navigate to Settings → Integrations → API Integrations → Data Export API. Click Configure. A modal pops up and displays the time and date your existing token was generated. Click Generate a new Access Token to generate a new token.

  2. A modal will pop up. Click I understand, generate a new token.

  3. The new token is issued, click the Copy button to copy the authentication token and store it in a secure place. The access token will be shown once at the time of generation. The next time you log in, the token will not be accessible through the console. Make sure API integrations are updated with this new token.

Data API Endpoint

https://{bot_handle_name}.ada.support/data_api/{version}

Replace {bot_handle_name} with your bot’s handle name

{version} is the version number of the endpoint in the format of v{Major}.{Minor} e.g. v1, v1.1

Ada developer slack channel

Clients with access to the Data Export API will be provided with an exclusive Ada developer slack channel where your team of developers will have direct access to our team in order to facilitate your implementation of the API.

Slack channel: #data-export-api-users

Clients can be added to this channel using their email address. If you have any technical difficulties with this Slack channel, email us.

You can use this channel to ask questions, raise issues, or get advice from the team that built the API.

Rate limits

The Data Export API is subject to rate limiting. If you exceed the rate limit, we may return a 429-Too Many Requests response status code.

We provide rate limits in order to ensure the stability of our infrastructure for all clients and the best experience for you. When calling the Data Export API you should implement 429 retry logic using exponential backoff and jitter.

The Data Export API rate limits are: 3 request / second for each endpoint

Page size and date range limitations

In addition to rate limits, we’ve implemented page size and date range limitations.

Page size limitations: maximum of 10,000 records per page

Date range limitations: the end date of the query must be 60 days or less from the start date

Data retention

The Data Export API can access data going back a maximum of 12 months.

Data ingestion time

It takes at least two hours to ingest conversation data into the Data API database. This means that queries won't return data from conversations created within the previous two hours. To capture data for a specific period, make sure you have passed that two hour window. For example, a query with a created_from of Feb 9 00:00:00 and a created_to of Feb 9 23:59:59, should run at Feb 10 2:00:00 or later to capture that entire 24-hour period.

Status Codes

Code Meaning
200 - OK The request was successfully processed by Ada
400 - Bad Request Incorrect query
408 - Request Timeout Database query timed out
422 - Unprocessable entity Invalid arguments or missing data for a required field
429 - Too many requests Requests are within 1 s of each other
500 - Bad request Request timed out or there was a database error
502 - Bad Gateway Nginx gateway issue on Ada's servers
503 - Service Unavailable Server temporarily unable to handle the request
504 - Gateway Timeout Temporary infrastructure error on Ada' servers

Pagination

Both the Conversations and Messages endpoints can be called using date range arguments and by specifying the number of results you’d like to recieve (via page size).

The response will contain the results requested and a next_page_uri. If there are more results than the specified page size, then continue paging through the data using the next_page_uri. The returned next_page_uri will be the same as the original URL you called, but the created_since (or updated_since for Conversations) will be changed to be the timestamp of the next result.

Pagination example

  {"next_page_uri":
  "/data_api/v1/messages?created_since=2020-09-23T03%3A55%3A03.586000&created_to=2020-09-28T00%3A00%3A00&page_size=100"}

Or

{"next_page_uri":
"/data_api/v1/conversations?updated_since=2020-09-23T03%3A55%3A03.586000&updated_to=2020-09-28T00%3A00%3A00&page_size=100"}

Example Usage

Grabbing all of the messages from yesterday

Continuously send GET requests until next_page_uri is null

Javascript Example

import fetch from "node-fetch"

async function fetchMessages() {
    const API_KEY = "<YOUR-API-KEY>"

    const startOfYesterday = new Date(), endOfYesterday = new Date()

    startOfYesterday.setDate(new Date().getDate() - 1)
    startOfYesterday.setHours(0)
    startOfYesterday.setMinutes(0)
    startOfYesterday.setSeconds(0)

    endOfYesterday.setDate(new Date().getDate() - 1)
    endOfYesterday.setHours(23)
    endOfYesterday.setMinutes(59)
    endOfYesterday.setSeconds(59)


    let endpoint = `data_api/v1/messages?created_since=${startOfYesterday.toISOString()}&created_to=${endOfYesterday.toISOString()}`

    while (endpoint) {
        const res = await fetch(`https://<YOUR-BOT-HANDLE>.ada.support/${endpoint}`,
            {
                headers: {
                    Authorization: `Bearer ${API_KEY}`
                }
            }
        )

        const json = await res.json()
        saveToDatabase(json.data)
        endpoint = json.next_page_uri
    }
}

Be sure to replace <YOUR-BOT-HANDLE> with your own bot handle, and <YOUR-API-KEY> with the key generated previously.

Python Example

from datetime import timedelta, date
from requests import get

def fetch_messages():
    API_KEY = "<YOUR-API-KEY>"
    yesterday = date.today() - timedelta(days=1)

    headers = {"Authorization": f"Bearer {API_KEY}"}
    endpoint = f"data_api/v1/messages?created_since={yesterday}T00:00:00&created_to={yesterday}T23:59:59"

    while endpoint:
        res = get(f"https://<YOUR-BOT-HANDLE>.ada.support/{endpoint}", headers=headers)      
        json = res.json()

        save_to_database(json["data"])
        endpoint = json["next_page_uri"]

Be sure to replace <YOUR-BOT-HANDLE> with your own bot handle, and <YOUR-API-KEY> with the key generated previously.

Data Export API Reference

Conversations resource

A conversation object is created any time a new chatter engages with Ada or a returning chatter starts a new conversation in accordance with your persistence settings in Ada.

Conversations are a higher-order object that contain messages (which can be accessed via the Messages endpoint).

Conversation Object Attributes

Attribute Description Type v1.0 v1.1
_id The conversations unique ID String
date_created The timestamp for when the conversation was created UTC Timestamp
date_updated The timestamp for when the conversation was last updated UTC Timestamp
chatter_id The unique chatter ID String
platform On which platform did the conversation take place String
is_engaged Did the chatter send at least one message to start the conversation after a greeting was served by Ada Boolean
is_escalated Did the chatter handoff to an integrated CX platform, an email ticket, or otherwise escalate to an agent Boolean
csat The associated CSAT score for the conversation JSON Dictionary
metavariables Gives the client access to the meta-variables we store JSON Dictionary
variables Gives the client access to the unique variable values for the conversation JSON Dictionary

Conversations endpoint

GET /data_api/v1/conversations

Parameters

Params Required? Default Value Type Example v1.0 v1.1
created_since One of created_since or updated_since is required NA UTC Timestamp 2020-09-21T00:00:00
updated_since One of created_since or updated_since is required NA UTC Timestamp 2020-09-21T00:00:00
created_to No 7 days range UTC Timestamp 2020-09-21T00:00:00
updated_to No 7 days range UTC Timestamp 2020-09-21T00:00:00
page_size No 10000 Integer 100

Returns

Returns a list of Conversation objects along with a status message and next_page_uri if applicable.

Examples

V1

Get all conversations that were created within 1 week of created_since

GET /data_api/v1/conversations?created_since=2020-09-21T04%3A30%3A22.681000%2B00%3A00&page_size=100

{
  "data": [
    {
      "_id": "<mongodb_12_byte_object_id>",
      "chatter_id": "<mongodb_12_byte_object_id>",
      "csat": {
        "comment": null,
        "feedback": [
          "(helpful_resolution)"
        ],
        "is_positive": true,
        "resolved": true,
        "score": 5,
        "style": "EMOJI",
        "survey_type": "end_chat"
      },
      "date_created": "2020-09-21T04:30:22.681000+00:00",
      "date_updated": "2020-09-21T04:33:57.614000+00:00",
      "is_engaged": true,
      "is_escalated": false,
      "metavariables": {
        "browser": "chrome",
        "browser_version": "85.0.4183.102",
        "device": "macos",
        "introshown": "False",
        "language": "en",
        "last_answer_id": "<mongodb_12_byte_object_id>",
        "last_question_asked": "Ada",
        "test_user": "1",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/85.0.4183.102 Safari/537.36"
      },
      "platform": "chat",
      "variables": {
        "name": "Ada"
      }
    }
  ],
  "message": "OK",
  "next_page_uri": "/data_api/v1/conversations?created_since=2020-09-25T15%3A00%3A26.906000&created_to=2020-09-28T00%3A00%3A00&page_size=100"
}

Get all conversations that were updated within 1 week of updated_since

GET /data_api/v1/conversations?updated_since=2020-09-21T04%3A30%3A22.681000%2B00%3A00&page_size=100

{
  "data": [
    {
      "_id": "<mongodb_12_byte_object_id>",
      "chatter_id": "<mongodb_12_byte_object_id>",
      "csat": {
        "comment": null,
        "feedback": [
          "(helpful_resolution)"
        ],
        "is_positive": true,
        "resolved": true,
        "score": 5,
        "style": "EMOJI",
        "survey_type": "end_chat"
      },
      "date_created": "2020-09-21T04:30:22.681000+00:00",
      "date_updated": "2020-09-21T04:33:57.614000+00:00",
      "is_engaged": true,
      "is_escalated": false,
      "metavariables": {
        "browser": "chrome",
        "browser_version": "85.0.4183.102",
        "device": "macos",
        "introshown": "False",
        "language": "en",
        "last_answer_id": "<mongodb_12_byte_object_id>",
        "last_question_asked": "Ada",
        "test_user": "1",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/85.0.4183.102 Safari/537.36"
      },
      "platform": "chat",
      "variables": {
        "name": "Ada"
      }
    }
  ],
  "message": "OK",
  "next_page_uri": "/data_api/v1/conversations?updated_since=2020-09-25T15%3A00%3A26.906000&updated_to=2020-09-28T00%3A00%3A00&page_size=100"
}

V1.1

Get all conversations that were created within 1 week of created_since

GET /data_api/v1.1/conversations?created_since=2020-09-21T04%3A30%3A22.681000%2B00%3A00&page_size=100

{
  "data": [
    {
      "_id": "<mongodb_12_byte_object_id>",
      "chatter_id": "<mongodb_12_byte_object_id>",
      "csat": {
        "comment": null,
        "feedback": [
          "(helpful_resolution)"
        ],
        "is_positive": true,
        "resolved": true,
        "score": 5,
        "style": "EMOJI",
        "survey_type": "end_chat"
      },
      "date_created": "2020-09-21T04:30:22.681000+00:00",
      "date_updated": "2020-09-21T04:33:57.614000+00:00",
      "is_engaged": true,
      "is_escalated": false,
      "metavariables": {
        "browser": "chrome",
        "browser_version": "85.0.4183.102",
        "device": "macos",
        "introshown": "False",
        "language": "en",
        "last_answer_id": "<mongodb_12_byte_object_id>",
        "last_question_asked": "Ada",
        "test_user": "1",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/85.0.4183.102 Safari/537.36"
      },
      "platform": "chat",
      "variables": {
        "name": "Ada"
      }
    }
  ],
  "message": "OK",
  "next_page_uri": "/data_api/v1.1/conversations?created_since=2020-09-25T15%3A00%3A26.906000&created_to=2020-09-28T00%3A00%3A00&page_size=100"
}

Get all conversations that were updated within 1 week of updated_since

GET /data_api/v1.1/conversations?updated_since=2020-09-21T04%3A30%3A22.681000%2B00%3A00&page_size=100

{
  "data": [
    {
      "_id": "<mongodb_12_byte_object_id>",
      "chatter_id": "<mongodb_12_byte_object_id>",
      "csat": {
        "comment": null,
        "feedback": [
          "(helpful_resolution)"
        ],
        "is_positive": true,
        "resolved": true,
        "score": 5,
        "style": "EMOJI",
        "survey_type": "end_chat"
      },
      "date_created": "2020-09-21T04:30:22.681000+00:00",
      "date_updated": "2020-09-21T04:33:57.614000+00:00",
      "is_engaged": true,
      "is_escalated": false,
      "metavariables": {
        "browser": "chrome",
        "browser_version": "85.0.4183.102",
        "device": "macos",
        "introshown": "False",
        "language": "en",
        "last_answer_id": "<mongodb_12_byte_object_id>",
        "last_question_asked": "Ada",
        "test_user": "1",
        "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/85.0.4183.102 Safari/537.36"
      },
      "platform": "chat",
      "variables": {
        "name": "Ada"
      }
    }
  ],
  "message": "OK",
  "next_page_uri": "/data_api/v1.1/conversations?updated_since=2020-09-25T15%3A00%3A26.906000&updated_to=2020-09-28T00%3A00%3A00&page_size=100"
}

Messages resource

A message object is created anytime either Ada or a chatter sends a message. All messages are associated with a conversation by a conversation_id.

Attribute Description Type v1.0 v1.1
_id The message’s unique ID String
date_created The timestamp for when the message was originally created UTC Timestamp
conversation_id A reference to the conversation object to which the message belongs String
chatter_id A reference to the chatter object to which the message belongs String
message_data An object containing the message content. (The message text is in the body property of the object) JSON Dictionary
sender The sender of the message (A unique ID if it is a chatter, or “agent” or “bot” otherwise) String
recipient The recipient of the message (A unique ID if it is a chatter, or “agent” or “bot” otherwise) String
review Was the answer given a thumbs up or thumbs down? Integer
answer_title The title of the answer in the builder interface String

message_data Examples

Greeting

"message_data": {
  "_type": "greeting",
  "external_chat_id": "<uuid_v4_id>",
  "reviewable_message": false
}

Text

"message_data": {
  "_type": "text",
  "body": "Hi there 👋 Nice to meet you! I’m Ada the chatbot 🤖",
  "has_variables": false,
  "reviewable_message": false
}

Picture

"message_data": {
  "_type": "picture",
  "alt_text": "Picture of a Ada art waving \"hello\"",
  "has_variables": false,
  "pic_url": "https://static.ada.support/images/4d096cfc-2518-4811-8443-e8c063262082.gif",
  "reviewable_message": false
}

Quick Reply

"message_data": {
  "_type": "quick_replies",
  "has_variables": false,
  "is_forced": false,
  "quick_replies": [
      {
          "button_type": "suggestion",
          "label": "Pricing",
          "target": "<mongodb_12_byte_object_id>"
      },
      {
          "button_type": "suggestion",
          "label": "Calculate your savings",
          "target": "<mongodb_12_byte_object_id>"
      },
      {
          "button_type": "suggestion",
          "label": "Request a Demo",
          "target": "<mongodb_12_byte_object_id>"
      },
      {
          "button_type": "suggestion",
          "label": "How can Ada help me? ",
          "target": "<mongodb_12_byte_object_id>"
      },
      {
          "button_type": "suggestion",
          "label": "How does Ada work with support teams?",
          "target": "<mongodb_12_byte_object_id>"
      },
      {
          "button_type": "suggestion",
          "label": "Download our Forrester Report",
          "target": "<mongodb_12_byte_object_id>"
      }
  ],
  "reviewable_message": false
}

Trigger

"message_data": {
  "_type": "trigger",
  "body": "Ask something else",
  "button_type": "suggestion",
  "external_chat_id": "<uuid_v4_id>",
  "reviewable_message": false
}

Meta

"message_data": {
  "_type": "meta",
  "meta_message_data": {
      "id": "<mongodb_12_byte_object_id>",
      "name": "last_answer_id",
      "new_value": "<mongodb_12_byte_object_id>",
      "old_value": "<mongodb_12_byte_object_id>",
      "scope": "meta"
  },
  "meta_message_type": "variable_change"
}
"message_data": {
  "_type": "link",
  "alt_text": "This is a link",
  "generate_link_preview": true,
  "has_variables": false,
  "is_handoff": false,
  "link_description": "",
  "link_icon": "",
  "link_text": "",
  "new_window": true,
  "raw_url": "https://www.example.com/",
  "reviewable_message": false,
  "title": "",
  "url": "https://www.example.com"
}

Web Window

"message_data": {
  "_type": "web_window",
  "has_forced_quick_replies": true,
  "has_variables": false,
  "is_handoff": false,
  "locked": false,
  "raw_url": "https://www.example.com",
  "reviewable_message": true,
  "window_button_label": "Open me",
  "window_height": 568,
  "window_title": "Webwindow",
  "window_url": "https://www.example.com",
  "window_width": 320
}

CSAT Prompt

"message_data": {
  "_type": "csat_shown",
  "survey_type": "proactive"
}

CSAT Result

"message_data": {
  "_type": "csat",
  "is_positive": true,
  "score": 5,
  "style": "NUMERIC",
  "survey_type": "proactive"
}

Messages endpoint

GET /data_api/v1/messages

Parameters

Params Required? Default Value Type Example v1.0 v1.1
created_since Yes NA UTC Timestamp 2020-09-21T00:00:00
created_to No 7 days UTC Timestamp 2020-09-21T00:00:00
page_size No 10000 Integer 100
conversation_id No NA String <mongodb_12_byte_object_id>

Returns

Returns a list of Messages objects along with a status message and next_page_uri if applicable.

Examples

V1

Get all messages that were created within 1 week of created_since

GET /data_api/v1/messages?created_since=2020-09-21T04%3A30%3A22.681000%2B00%3A00&page_size=100


{
  "data": [
    {
      "_id": "<mongodb_12_byte_object_id>",
      "answer_title": null,
      "conversation_id": "<mongodb_12_byte_object_id>",
      "date_created": "2020-09-21T04:30:22.268000+00:00",
      "message_data": {
        "_type": "greeting",
        "external_chat_id": "<uuid_v4_id>",
        "reviewable_message": false
      },
      "recipient": "ada",
      "review": 0,
      "sender": "<uuid_v4_id>"
    },
    {
      "_id": "<mongodb_12_byte_object_id>",
      "answer_title": null,
      "conversation_id": "<mongodb_12_byte_object_id>",
      "date_created": "2020-09-21T04:30:23.256000+00:00",
      "message_data": {
        "_type": "meta",
        "meta_message_data": {
          "id": "<mongodb_12_byte_object_id>",
          "name": "browser",
          "new_value": "chrome",
          "old_value": null,
          "scope": "meta"
        },
        "meta_message_type": "variable_change"
      },
      "recipient": "<uuid_v4_id>",
      "review": 0,
      "sender": "bot"
    }
  ],
  "message": "OK",
  "next_page_uri": "/data_api/v1/messages?created_since=2020-09-23T03%3A55%3A03.586000&created_to=2020-09-28T00%3A00%3A00&page_size=100"
}

V1.1

Get all messages that were created within 1 week of created_since

GET /data_api/v1.1/messages?created_since=2020-09-21T04%3A30%3A22.681000%2B00%3A00&page_size=100


{
  "data": [
    {
      "_id": "<mongodb_12_byte_object_id>",
      "answer_title": null,
      "conversation_id": "<mongodb_12_byte_object_id>",
      "chatter_id": "<mongodb_12_byte_object_id>",
      "date_created": "2020-09-21T04:30:22.268000+00:00",
      "message_data": {
        "_type": "greeting",
        "external_chat_id": "<uuid_v4_id>",
        "reviewable_message": false
      },
      "recipient": "ada",
      "review": 0,
      "sender": "<uuid_v4_id>"
    },
    {
      "_id": "<mongodb_12_byte_object_id>",
      "answer_title": null,
      "conversation_id": "<mongodb_12_byte_object_id>",
      "chatter_id": "<mongodb_12_byte_object_id>",
      "date_created": "2020-09-21T04:30:23.256000+00:00",
      "message_data": {
        "_type": "meta",
        "meta_message_data": {
          "id": "<mongodb_12_byte_object_id>",
          "name": "browser",
          "new_value": "chrome",
          "old_value": null,
          "scope": "meta"
        },
        "meta_message_type": "variable_change"
      },
      "recipient": "<uuid_v4_id>",
      "review": 0,
      "sender": "bot"
    }
  ],
  "message": "OK",
  "next_page_uri": "/data_api/v1.1/messages?created_since=2020-09-23T03%3A55%3A03.586000&created_to=2020-09-28T00%3A00%3A00&page_size=100"
}

Data API Changelog

Revision History

Date Description
2021.05.09 Data older than 12 months is not accessible via the Data Export API.
2021.05.09 For reporting purposes, consider that it takes at least two hours to ingest conversation data into the Data API database.
2021.02.24 Data API v1 first available for early access clients. Message, Conversation endpoints published.
2021.06.22 Added additional request timed out error code (408).
2021.07.29 Added self-serve auth key generation in UI portal under Data API feature flag. Beta Release v1 for additional clients.
2021.08.10 Added Data API base URI endpoint in Data Export API UI portal under settings/integrations.
2021.08.30 Data API v1.1 release, the following are the changes available for v1.1
  • chatter_id field available in messages endpoint response field
  • filter by chatter_id or conversation_id for messages endpoint
Added 30 days expiration token for trial accounts.
2021.11.03 Added CSAT response examples for the Conversation endpoint.
2022.03.04 Removed Chatter ID filtering support for the Messages endpoint.
2022.05.20 Update images and examples with new Data Export API endpoint.

Data Compliance API

Description

The Data Compliance API provides an endpoint for sending data compliance requests (such as those required by GDPR) on behalf of your clients. Currently the api only supports "ERASURE" requests, which delete all data associated with a specific user from our systems.

Requirements

  1. Data Compliance API Key

Generating your API Key

  1. Navigate to Settings → Integrations → API Integrations → Data Compliance API. Click Configure.

  2. A modal will pop up. Click Generate a new Access Token.

  3. The token is created, click the Copy button to copy the authentication token and store it in a secure place. The access token will be shown once at the time of generation. Once you close the modal, your access token will no longer be available.

You now can use this Bearer token as the authorization header to access the Data Compliance API, following this format:

Headers:

Key Value
Authorization Bearer <your_api_token>

Data Subject Request endpoint

Request to delete all data associated with a client.

POST https://<BOT_HANDLE>.ada.support/api/v1/data-subject-request

Where <BOT_HANDLE> is replaced with your bot handle.

Request Headers

Key Value
Authorization Bearer <your_api_token>

Request Parameters

Params Description Required? Default Value Type Example
email Email of the client whose data you wish to delete from Ada's systems. Yes NA String example@example.com
type Type of data subject request. Must be set to "ERASURE". More types may be added in the future. Yes NA String ERASURE
identifiers List containing additional emails. Format must be: [{"type": "email", "value": "email_address"}] No NA JSON Object [{"value": "example-2@example.com", "type": "email"},{"value": "example-3@example.com", "type": "email"}]

Response Parameters

Params Description Type Example
email Email of the client whose data will be deleted from Ada's systems. String example@example.com

Rate Limiting

There is no limit on the number of deletion requests you can send. However, the system ingests requests at a rate of 45 requests per second.

Status Codes Meanings

Code Meaning
200 - OK The request was successfully processed by Ada
400 - Unauthorized Invalid request body or headers
401 - Unauthorized Authentication token is invalid or does not have the correct permissions. Try generating a new token.
429 - Too many requests Request quota exceeded
500 - Bad request Something went wrong on Ada's end
502 - Bad Gateway Nginx gateway issue on Ada's servers
503 - Service Unavailable Server temporarily unable to handle the request
504 - Gateway Timeout Temporary infrastructure error on Ada' servers

Code Examples

Python

import requests
api_key = "YOUR API KEY"
bot_handle = "YOUR BOT HANDLE"
url = f"https://{bot_handle}.ada.support/api/v1/data-subject-request"
client_to_delete = "example@example.com"
extra_identifiers = [{"type": "email", "value": "example-2@example.com"}]
body = {"email": client_to_delete, "identifiers": extra_identifiers, "type": "ERASURE"}
headers = {"Authorization": f"Bearer {api_key}"}
res = requests.post(url=url, json=body, headers=headers)
if res.status_code != 200:
   print(f"Request failed: {res.text}")
else:
   print(f"Success: {res.json()}")

Questions

Need some help? Get in touch with us at help@ada.support.