> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.ada.cx/chat/android/sdk-api-reference/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server.

# SDK API Reference

> **Warning**
>
> Ada has deprecated Chat. Messaging fully replaces Chat on December 15, 2026. Read [Introducing Messaging](https://docs.ada.cx/2026-09-30-introducing-messaging) to learn how to migrate.

This page covers the legacy Chat Android SDK. Follow the [Messaging Android upgrade guide](/messaging/android/getting-started#upgrade-from-the-existing-android-sdk) to migrate.

With the Android SDK, you can customize the behavior of your chat bot by configuring initial chat settings, either in XML or programmatically using the `AdaEmbedView.Settings` class.

**`XML`**

```xml XML
<!-- 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_greeting="5c59aaabd8269e0339979014"/>
```

**`Kotlin`**

```kotlin Kotlin
//Example 2: Kotlin
val adaSettings = AdaEmbedView.Settings.Builder("ada-example")
    .cluster("ca")
    .greeting("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()
```

## Settings

The Ada Android SDK supports the following settings.

### cluster

`app:ada_cluster="ca"` or `.cluster("ca")`

Specifies the Kubernetes cluster your AI Agent runs on.
**Set this only if your Agent is hosted on a non-default cluster** (e.g., `us2`, `maple`, `eu`).
If the Agent is on the default `us` cluster, leave this unset.

> **Info**
>
> Do not change this value unless instructed by your Ada team.

### greeting

`app:ada_greeting="5c59aaabd8269e0339979014"` or `.greeting("5c59aaabd8269e0339979014")`

Use to customize the greeting messages that new chatters 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, which you can find in the URL of the corresponding Answer in the dashboard.

**Example**

![](/_fern-img/a7fea47cff8a7e0931f1f7b88be30130fc81ec7c6be9d662433b766b8e037e0b.webp)

> **Note**
>
> This setting is only applicable if you're using a **scripted bot**.

### handle

`app:ada_handle="my-bot"` or `adaSettings = AdaEmbedView.Settings.Builder("my-bot")`

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

### language

`app:ada_language="en"` or `.language("en")`

Takes in a language code to programatically set the bot language. You must first turn languages on in your Ada dashboard.

* If you're using a **generative AI Agent**, go to **Customization** > **Languages**. See [Support multiple languages in the same AI Agent](/docs/setup/languages/about-multilingual-support) for more information.

> **Note**
>
> Language codes use the [ISO 639-1 language format](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).

### metaFields

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](https://docs.ada.cx/variables) for more information.)

Once set, you can access this information:

* in the email attachment from Handoff Form submissions
* via the **Meta variables** modal in the **Conversations** page of your Ada dashboard

**`Kotlin`**

```kotlin Kotlin
  .metaFields(
        AdaEmbedView.MetaFields.Builder()
                .setField("name", "John")
                .setField("age", 20)
                .setField("authorized", true)
    )
```

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

To change these values after bot setup, use the [setMetaFields](/chat/android/sdk-api-reference#setmetafields) action.

### sensitiveMetaFields

Use this parameter to pass sensitive meta information about a chatter. This works like [metafields](/chat/android/sdk-api-reference#metafields) but the values are not stored in the database and will be deleted after 24 hours. To change these values after bot setup, use the  [setSensitiveMetafields](/chat/android/sdk-api-reference#sensitivemetafields) action.

### zdChatterAuthCallback

Use the `zdChatterAuthCallback` 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.

To implement, define `zdChatterAuthCallback` on `adaView` or `adaDialog`, as in the following examples.

**Using AdaEmbedView**

**`Kotlin`**

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

**Using AdaEmbedDialog**

**`Kotlin`**

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

> **Note**
>
> `zdChatterAuthCallback` is available only for [Zendesk Chat](https://docs.ada.cx/docs/generative/integrate-ada-with-other-tools/use-ada-with-zendesk/configure-zendesk-chat). It is not available for [Zendesk Messaging](https://docs.ada.cx/docs/generative/integrate-ada-with-other-tools/use-ada-with-zendesk/configure-and-use-zendesk-messaging/).

## Session Persistence

The Android SDK stores session state — including the chatter token and any active Zendesk Messaging handoff context — in the WebView's `localStorage`.

> **Warning**
>
> **On Android, WebView `localStorage` is not guaranteed to survive a force-quit.** If a user force-closes the app during an active session or live agent handoff, their conversation state will be lost when they reopen the app.
>
> If your app requires session continuity across app restarts, you will need to implement your own native storage management. The current SDK does not persist session state using platform-native storage such as `SharedPreferences`.
>
> To implement this yourself, see the Android developer documentation on [saving key-value data with SharedPreferences](https://developer.android.com/training/data-storage/shared-preferences).

## Actions

Use the actions below in conjunction with settings to customize the behavior of your bot in an Android app.

> **Note**
>
> Note that the following actions apply to `AdaEmbedView` (see [Launch Ada](/chat/android/getting-started#launch-ada)). To call actions in `AdaEmbedActivity` or `AdaEmbedDialog`, refer to [these instructions](/chat/android/getting-started#file-upload-support).

### deleteHistory

**`Kotlin`**

```kotlin Kotlin
adaView.deleteHistory()
```

Deletes the chatter used to fetch conversation logs for a `chatter` from storage. When a user opens a new chat window, a new `chatter` is generated.

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

### reset

Creates a new chatter and refreshes the chat window. To do this, call `reset()` in your `AdaEmbedView` instance.

**`Kotlin`**

```kotlin Kotlin
adaView.reset()
```

Reset can also take three optional parameters to be changed for the new chatter: `language`, `metaFields`, and `greeting`:

**`Kotlin`**

```kotlin Kotlin
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)
```

### setLanguage

`setLanguage(languageCode: string)`

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](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). For example, en, fr, ca, ar, and so on.

```
adaView.setLanguage("fr")
```

Before using `setLanguage`:

* You must turn languages on in your Ada dashboard.
  * If you're using a **generative AI Agent**, go to **Customization** > **Languages**. See [Support multiple languages in the same AI Agent](/docs/setup/languages/about-multilingual-support) for more information.

* The chat window must be opened at least once.

### setMetaFields

The Android SDK allows you to change your [metaFields](/chat/android/sdk-api-reference#metafields) while the chat frame is open. To do this, call `setMetaFields()` in your `AdaEmbedView` instance, and pass your new metaFields as an argument:

**`Kotlin`**

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

### setSensitiveMetaFields

The Android SDK allows you to change your [sensitiveMetaFields](/chat/android/sdk-api-reference#sensitivemetafields) while the chat frame is open. To do this, call `setSensitiveMetaFields()` in your `AdaEmbedView` instance and pass your new sensitiveMetaFields as an argument:

**`Kotlin`**

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

### triggerAnswer

`adaView.triggerAnswer(answerId: string)`

Triggers an answer in chat. Include the Answer ID, which you can find in the URL of the corresponding Answer in the dashboard.

**Example**

![](/_fern-img/a7fea47cff8a7e0931f1f7b88be30130fc81ec7c6be9d662433b766b8e037e0b.webp)

```
adaView.triggerAnswer("627d28a9bd9ca9e5337b9763")
```

> **Note**
>
> The chat window must be opened at least once before this method can be used.

> **Note**
>
> This action is only applicable if you're using a **scripted bot**.

## AdaEmbedActivity and AdaEmbedDialog

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

**`Kotlin`**

```kotlin Kotlin
// 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 `AdaEmbedDialog`, you can obtain `AdaEmbedDialog` instance from FragmentManager:

**`Kotlin`**

```kotlin Kotlin
// 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()
```