Android SDK reference

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.

<!-- 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"/>

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

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

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 for more information.
• If you're using a scripted bot, go to Settings > Bot setup > Multilingual. See Support multiple languages in the same bot for more information.

📘

Language codes use the ISO 639-1 language format.

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

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

sensitiveMetaFields

Use this parameter to pass sensitive meta information about a chatter. This works like 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 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

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

Using AdaEmbedDialog

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

Actions

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

📘

Note that the following actions apply to AdaEmbedView (see Launch Ada). To call actions in AdaEmbedActivity or AdaEmbedDialog, refer to these instructions.

deleteHistory

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.

adaView.reset()

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

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. 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 Review and analyze conversation topics for more information.
  • If you're using a scripted bot, go to Settings > Bot setup > Multilingual. See Track conversation topics for more information.

• The chat window must be opened at least once.

setMetaFields

The Android SDK allows you to change your metaFields while the chat frame is open. To do this, call setMetaFields() in your AdaEmbedView instance, and pass your new metaFields as an argument:

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 while the chat frame is open. To do this, call setSensitiveMetaFields() in your AdaEmbedView instance and pass your new sensitivemMetaFields as an argument:

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

adaView.triggerAnswer("627d28a9bd9ca9e5337b9763")

📘

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

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.

// 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:

// 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()