SDK API reference

With the Android SDK, you can customize the behavior of your AI Agent by configuring initial settings, either in XML or programmatically using the AdaMessagingView.Settings class.

<!-- Example 1: XML -->
<cx.ada.messaging.widget.AdaMessagingView
    android:id="@+id/ada_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:ada_handle="my-handle"
    app:ada_language="en"
    app:ada_greeting="5c59aaabd8269e0339979014" />

Settings

The Ada Android SDK supports the following settings on AdaMessagingView.Settings.Builder. Settings that also have an XML attribute list it next to the builder method.

acceptThirdPartyCookies

app:ada_accept_third_party_cookies="true" or .acceptThirdPartyCookies(true)

Allows the WebView to accept third-party cookies. Defaults to false. Only set this if an Ada integration you use requires it.

appUrl

.appUrl("https://apps.example.com/ada-app/")

Overrides the app frame URL that the Messaging runtime mounts.

Your handle’s Allowed websites list controls custom apps. In your dashboard, go to Channels > Messaging. Before your transition, use Channels > Chat. Add your app’s origin. If the list does not allow the origin, the runtime drops the URL with a logged warning and mounts the default app.

The value must be an absolute https: URL. The runtime drops invalid values with a logged warning and mounts the default app instead. If the custom app fails to load or complete its handshake, the runtime falls back to the default app.

For local development against an emulator, expose your development server through an https: tunnel, and add the tunnel origin to Allowed websites. The dashboard accepts only https:// entries. On the production and pre-production environments, the WebView’s host page is an Ada asset origin, not a loopback page. The web SDK’s implicit loopback allowance therefore does not apply there. The emulator reaches the tunnel origin directly, so no port forwarding is needed.

The exception is the local asset-server environment (AdaEnvironment.Local), used for SDK development. Its WebView host page is https://localhost:4900, a loopback origin, so the implicit loopback allowance applies and a loopback appUrl needs no entry. The emulator’s 10.0.2.2 host alias is not a loopback host, so the runtime rejects it as an appUrl. A host page served from that alias also loses the implicit allowance, for the same reason. Instead, forward the port so the emulator reaches your development server at http://localhost:5173:

adb reverse tcp:5173 tcp:5173

The SDK delivers the value to the web runtime through an injected configuration object, not through the WebView URL. Unlike identityToken, which is delivered once, the value is delivered again on every document load. See Custom apps. Ignored on the Legacy runtime.

cluster

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

Specifies the cluster your AI Agent runs on. Set this only if your Agent is hosted on a non-default cluster. If the Agent is on the default cluster, leave this unset.

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

deviceToken

app:ada_device_token="fcm-device-token" or .deviceToken("fcm-device-token")

The FCM device token for push notifications. The SDK forwards the token at initialization on both the Legacy and Messaging runtimes. It is present from the first message the end user sends. On the Messaging runtime, this differs from iOS and React Native, which register the token only once the runtime is ready. Use this so end users can receive push notifications for new messages while the app is closed. To change the token after initialization, use the setDeviceToken action.

domain

.domain("acme")

The Ada domain your AI Agent is served from. Applies to the Legacy runtime only. The Messaging runtime resolves its host from cluster and environment.

Do not set this value unless instructed by your Ada team.

embedVersion

.embedVersion("<build-sha>")

Pins the Legacy runtime to a specific embed build for pre-release validation. Leave blank for the stable rollout. Ignored on the Messaging runtime.

Only use this when the Ada team gives you a build to validate.

enableProgrammaticControl

.enableProgrammaticControl(true)

Opts your app into the Messaging runtime’s programmatic control surface. Defaults to false. When set to true, your app can:

Call sendMessage.
Receive the ada:message:sent and ada:message:received events through addEventCallback.

While the flag is false, the runtime rejects sendMessage with a ProgrammaticControlNotEnabled error, and those events are not delivered to your callbacks.

Ignored on the Legacy runtime, which has no such gate.

Turning this on delivers full message bodies to your native code. The ada:message:sent and ada:message:received events carry the conversation transcript, including any PII your end users type. Have your product and security teams accept that exposure explicitly before you enable it.

environment

.environment(AdaEnvironment.Production)

Selects the Ada deployment environment. Defaults to production. See the AdaEnvironment type for the available values. Most apps never set this.

greeting

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

Customizes the greeting message that new end users see. The value is the ID of the Answer you want to use. You can find the ID in the URL of the corresponding Answer in the dashboard.

This setting only applies if you’re using a scripted AI Agent.

The plural forms .greetings(...) and app:ada_greetings are accepted as compatibility aliases. Use the singular greeting form in new code.

handle

app:ada_handle="my-handle" or AdaMessagingView.Settings.Builder("my-handle")

The handle for your AI Agent. This is a required field, passed as the Settings.Builder constructor argument.

headless

.headless(true)

Runs the Messaging runtime without its default UI. Defaults to false. The runtime still boots, connects, and emits events, and programmatic commands such as sendMessage still work. Only the rendered conversation surface is suppressed.

Use this when your app renders its own conversation UI, or when it only consumes conversation events. Pair it with the AdaMessagingView.headless factory to run the view without attaching it to a layout, and with enableProgrammaticControl when you need sendMessage.

Ignored on the Legacy runtime. See Headless mode.

Headless sessions run with no visual indicator to the end user. The conversation session is created the same way as a visible session. Treat enabling headless as a meaningful trust decision for your app.

identityToken

.identityToken(token)

Authenticates the end user with a one-shot identity token minted by your backend. The Messaging runtime exchanges the token for an authenticated session during startup.

The flow is:

Your backend requests a short-lived, single-use JWT for the signed-in end user from Ada’s POST /v2/auth/tokens/ endpoint.
Your app passes that token to .identityToken(...) when it builds the settings.
The runtime performs the exchange before the conversation starts.

Kotlin

val settings = AdaMessagingView.Settings.Builder("my-handle")
    .webSdk(AdaWebSdk.Messaging)
    .identityToken(tokenFromYourBackend)
    .build()

Each token is single-use and expires quickly. Mint a fresh token from your backend for each initialization. Do not reuse tokens, and do not mint them on the device.

The SDK hands the token to the runtime through a secure native channel. The token never appears in a URL, and the SDK never persists it to disk.

Exchange failures surface as the ada:identity_token:error and ada:identity_token:expired events through addEventCallback.

Ignored on the Legacy runtime.

language

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

Sets the initial display language. To use the same language for AI Agent replies, first turn languages on in your Ada dashboard. Go to Customization > Languages. See Support multiple languages in the same AI Agent for more information.

With the Messaging runtime, this setting applies on every WebView launch and takes precedence over a saved language choice. A language picker or setLanguage change during that launch is still saved when session persistence is enabled. This setting takes precedence again on the next launch. Omit this setting to allow a saved choice to restore.

Later language updates from the Agent or another widget sharing the session can change the display language. With session persistence enabled, the widget saves its current display language.

When activation restores an existing session, it synchronizes the configured language if the Agent supports it. If the reply language changes, other open widgets using the same session apply the update live, even during a conversation.

If the Agent does not support the display language, or the language update fails, the display language can differ from the Agent’s reply language. An unsupported configured value can still replace a supported saved choice when session persistence is enabled.

Language codes use the ISO 639-1 language format.

loadTimeoutMillis

app:ada_load_timeout="10000" or .loadTimeoutMillis(10000)

Sets the WebView load timeout in milliseconds. Defaults to 30000. When the timeout elapses before the conversation loads, the SDK invokes webViewLoadingErrorCallback.

metaFields

app:ada_metaFields="@raw/meta_fields" or .metaFields(builder)

Passes information about an end user to Ada. Use this to track information about your end users, and to personalize their experience. For example, you may wish to track the phone_number and name for conversation attribution.

Kotlin

.metaFields(
    AdaMessagingView.MetaFields.Builder()
        .setField("name", "John")
        .setField("age", 20)
        .setField("authorized", true),
)

To set metaFields in XML, create a JSON file in the res/raw directory, and reference it from the view declaration.

To change these values after initialization, use the setMetaFields action.

sensitiveMetaFields

app:ada_sensitiveMetaFields="@raw/sensitive_meta_fields" or .sensitiveMetaFields(builder)

Passes sensitive information about an end user. This works like metaFields, but the values are not stored in the database, and are deleted after 24 hours.

The SDK forwards these fields at initialization, so an identified session carries them from the first message. On the Legacy runtime they ride the start config. On the Messaging runtime they ride a document-start injection. The values never appear in a URL.

To change these values after initialization, use the setSensitiveMetaFields action.

styles

app:ada_styles="..." or .styles("...")

Passes style overrides to the conversation. The value’s meaning depends on the runtime:

Legacy runtime: a CSS style override string, forwarded to the conversation frame.
Messaging runtime: no effect. The runtime ignores the value and logs a warning.

version

.version("<build-sha>")

Pins the Legacy runtime’s conversation UI to a specific build for pre-release validation. Leave blank for the stable rollout. Ignored on the Messaging runtime.

Only use this when the Ada team gives you a build to validate.

webSdk

app:ada_web_sdk="legacy|messaging" or .webSdk(AdaWebSdk.Messaging)

Selects the web runtime the SDK loads. Defaults to AdaWebSdk.Legacy, which preserves the behavior of Ada’s existing Chat SDK. Set AdaWebSdk.Messaging to use the next-generation Messaging runtime.

The enableProgrammaticControl, headless, and identityToken settings, and the sendMessage action’s programmatic gate, apply to the Messaging runtime only.

Callback properties

Set these properties directly on your AdaMessagingView instance.

filePickerCallback

Fires when an end user requests to attach a file. Launch your file picker, then invoke callback.onFileTaken(uri) with the chosen URI. Pass null to cancel the request. Return true to signal that your app handles the picker flow.

Kotlin

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

AdaMessagingActivity and AdaMessagingDialog handle file selection for you.

webViewErrorCallback

Fires whenever webViewLoadingErrorCallback fires, with a typed AdaWebViewError that describes the reason. When both callbacks are set, both fire.

Kotlin

adaView.webViewErrorCallback = { error ->
    when (error) {
        is AdaWebViewError.Timeout -> showRetry()
        is AdaWebViewError.HttpError -> log(error.statusCode)
        is AdaWebViewError.LoadFailed -> log(error.description)
        is AdaWebViewError.BridgeError -> log(error.error)
    }
}

webViewLoadingErrorCallback

Fires when the conversation fails to load, including when loadTimeoutMillis elapses. To learn why the load failed, set webViewErrorCallback instead, or in addition.

Kotlin

adaView.webViewLoadingErrorCallback = {
    // Show your own error state or retry.
}

zdChatterAuthAsyncCallback

Use this variant of zdChatterAuthCallback to fetch JWTs over the network for Zendesk Chat and Zendesk Messaging Handoffs. The SDK invokes your callback with a respond function. Call respond(token) from any thread when your request completes. Call respond(null) if no token is available. For Zendesk Messaging, authentication failure lets the Handoff proceed with an anonymous Sunshine user when no other identity mapping applies.

Kotlin

adaView.zdChatterAuthAsyncCallback = { respond ->
    fetchTokenFromApi { token ->
        respond(token)
    }
}

The SDK accepts one answer per request and drops late answers for a superseded request. When both callbacks are set, zdChatterAuthAsyncCallback takes precedence.

zdChatterAuthCallback

Use zdChatterAuthCallback to authenticate Zendesk Chat and Zendesk Messaging Handoffs with a JWT from your server.

Kotlin

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

The SDK invokes this callback on the main thread, so it must return quickly. To fetch the token over the network, use zdChatterAuthAsyncCallback instead.

For Zendesk Messaging, return your Zendesk Messaging authentication JWT. Sign it with a Zendesk Messaging signing key using HS256. Include the signing key ID in the kid header. Include the scope: "user", external_id, and exp claims. Set exp to an expiry time in Unix seconds. Keep the signing secret on your server.

The external_id must be a non-empty string of at most 255 characters. It must not contain /, ?, #, %, whitespace, or control characters. The JWT can include name and email, but Ada does not store these claims for Messaging authentication.

The SDK requests one token at startup, including when both Zendesk platforms are configured. Zendesk Messaging authentication does not require the Zendesk Chat feature. Existing Zendesk Chat callbacks need no changes.

Ada finds or creates the Sunshine user under that external_id when the Handoff starts.

After successful verification, the server stores the identity and its validity window on the end user record. Each successful startup check renews the window for 24 hours. Browser metadata cannot supply or change these values.

If no valid token or signing secret is available, the Handoff uses an anonymous Sunshine user unless another identity mapping applies. When a user signs out, call adaView.reset() so the next user starts a new conversation and a new Zendesk user. See Authenticate end users for signing key setup.

The Android SDK invokes this callback on the Messaging runtime only. On the Legacy runtime, a Zendesk Chat handoff proceeds unauthenticated.

Actions

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

The following actions apply to AdaMessagingView. To call actions on AdaMessagingActivity or AdaMessagingDialog, see AdaMessagingActivity and AdaMessagingDialog.

Actions called before the runtime reports ready are queued, then run once the sdk.ready event fires.

addEventCallback

addEventCallback(eventName: String = "*", callback: (event: Event) -> Unit)

Subscribes to conversation events. Pass an exact event key to receive only that event, or omit the key to receive every forwarded event through the "*" catch-all.

Kotlin

adaView.addEventCallback("ada:message:received") { event ->
    // A message from the AI Agent arrived.
}
adaView.addEventCallback { event ->
    Log.d("Ada", "event=${event.eventName}")
}

Useful event keys include:

ada:identity_token:error and ada:identity_token:expired report identityToken exchange failures.
ada:message:received and ada:message:sent fire per message on the Messaging runtime, and require enableProgrammaticControl.
ada.bridge.error reports a native bridge error.
ada.webview.loaded, ada.webview.loadFailed, ada.webview.subresourceLoadFailed, and ada.webview.mainDocumentLost report the WebView’s own lifecycle. See WebView lifecycle events.
ada.sessionMirror.diagnostic reports a degraded session mirror. See WebView lifecycle events.
sdk.ready fires when the runtime is ready for commands.

Remove subscriptions with removeEventCallback(callback) or removeEventCallbacks(eventName).

addSdkEventCallback

addSdkEventCallback(callback: (key: String, data: String?) -> Unit)

Subscribes to every event with its raw key and JSON payload. Use this instead of addEventCallback when you need the unparsed payload. Remove subscriptions with removeSdkEventCallback(callback).

clearPersistedState

adaView.clearPersistedState()

Removes the SDK’s natively persisted state. This includes the cached branding snapshot that smooths the next launch. From version 1.2.0, it also includes the persisted session mirror. Call it when an end user signs out. The next session starts without rehydrated state. See Session persistence.

The method returns no result. It runs the wipe in the background. It does not block the calling thread, so it is safe to call on the main thread. To confirm the wipe, use clearPersistedStateDurably.

The call works before initialize. It does not touch the web runtime’s own storage. To clear the conversation itself, use deleteHistory or reset.

clearPersistedStateDurably

adaView.clearPersistedStateDurably(): Boolean

Removes the same natively persisted state as clearPersistedState, and returns the result. The method returns false when the SDK could not confirm the session-mirror wipe on disk. If the method returns false, call it again.

This method blocks the calling thread. It runs the wipe in the background, and the caller waits. The wait ends when the wipe completes or a timeout of about 3 seconds elapses. Call it off the main thread. Use it when your sign-out flow must confirm the wipe before it continues.

deleteHistory

adaView.deleteHistory()

Deletes the end user’s conversation history from storage. When the end user opens a new conversation, the SDK creates a new end-user record.

initialize

adaView.initialize(settings)

Initializes the view with an AdaMessagingView.Settings object and starts loading the conversation. Required when the view was created programmatically, or when the XML declaration has no ada_handle attribute.

reset

adaView.reset()

Creates a new end-user session and refreshes the conversation.

Reset can also take optional parameters to apply to the new session: language, greetings, metaFields, sensitiveMetaFields, and resetChatHistory:

Kotlin

adaView.reset(
    language = "en",
    metaFields = AdaMessagingView.MetaFields.Builder()
        .setField("plan", "pro"),
    sensitiveMetaFields = AdaMessagingView.MetaFields.Builder()
        .setField("authToken", "secure-session-token"),
    resetChatHistory = true,
)

sendMessage

adaView.sendMessage(message: String)

Sends a message into the conversation on the end user’s behalf, as if they had typed it. Calls queue until the runtime reports sdk.ready, so you can call it right after initialize.

Kotlin

adaView.sendMessage("I need help with my order")

On the Messaging runtime, the send is rejected with a ProgrammaticControlNotEnabled error unless you set enableProgrammaticControl(true).

setDeviceToken

adaView.setDeviceToken(token: String)

Registers or updates the device’s push notification token. Use this so end users can receive push notifications for new messages while the app is closed.

setLanguage

adaView.setLanguage(language: String)

Changes the conversation language programmatically. Use this action, rather than the language setting, to change the language without clearing the conversation history. Language codes must use a lowercase, two-letter ISO 639-1 code.

Kotlin

adaView.setLanguage("fr")

Before using setLanguage, you must turn languages on in your Ada dashboard. Calls made before the runtime reports sdk.ready are queued and dispatched when it becomes ready, so you can call it right after initialize.

setMetaFields

Changes your metaFields while the conversation is open:

Kotlin

adaView.setMetaFields(
    AdaMessagingView.MetaFields.Builder()
        .setField("name", "John")
        .setField("age", 20)
        .setField("authorized", true),
)

setSensitiveMetaFields

Changes your sensitiveMetaFields while the conversation is open:

Kotlin

adaView.setSensitiveMetaFields(
    AdaMessagingView.MetaFields.Builder()
        .setField("authToken", "rotated-session-token"),
)

Map<String, String> overloads for setMetaFields, setSensitiveMetaFields, and reset still exist for backward compatibility, but are deprecated. Use MetaFields.Builder for all new code.

Curated bridge requests

AdaMessagingView exposes a fixed set of methods that ask the running chat for state or drive it. Each method takes a callback. The callback receives one AdaBridgeInterface.AdaBridgeResponse. That response is Success, Unsupported, or Failure.

A method returns Unsupported when the running runtime build does not implement it. A method returns Failure in any of three cases:

The runtime returns an error, such as a bad argument.
No answer arrives before the request times out.
The runtime sends a malformed response that carries none of a result, an error, or an unsupported outcome.

A method never silently does nothing.

Reads return public models only. No read returns sensitive meta fields, the internal stores, or persisted session data. Writes and triggers succeed with a null result.

Calls made before the runtime reports sdk.ready are queued, then run once it becomes ready. Reads take a required callback. Writes and triggers take an optional callback. Only the message reads getConversation and getMessages require enableProgrammaticControl. That setting defaults to false. The other reads, writes, and triggers do not. The default differs per platform. React Native defaults it to true. There the same two reads resolve without the flag.

Method	Result	Description
`close(callback)`	`Unsupported`	The SDK cannot close a parent-hosted webview.
`closeCampaign(callback)`	`Success` with null	Dismisses the active campaign.
`getConversation(callback)`	`Success` with the model	The public conversation model.
`getInfo(callback)`	`Success` with the model	The public AI Agent and session info.
`getMessages(callback)`	`Success` with the model	The public message list.
`getMetaFields(callback)`	`Success` with the model	The non-sensitive meta fields set on the session.
`isOpen(callback)`	`Success` with the value	Whether the chat window is open.
`open(callback)`	`Unsupported`	The SDK cannot open a parent-hosted webview.
`setTheme(theme, callback)`	`Success` with null	Sets the runtime theme to `"light"`, `"dark"`, or `"auto"`.
`toggle(callback)`	`Unsupported`	The SDK cannot toggle a parent-hosted webview.
`triggerAnswer(answerId, callback)`	`Success` with null	Triggers a specific answer by id.
`triggerGreeting(handle, callback)`	`Success` with null	Triggers the greeting, optionally for a specific handle.
`triggerProactive(messageKey, params, callback)`	`Success` with null	Shows a proactive message by key, with optional variable substitutions.

Kotlin

adaView.getConversation { response ->
    if (response is AdaBridgeInterface.AdaBridgeResponse.Success) {
        // Use the public conversation model.
    }
}
adaView.setTheme("dark")

WebView lifecycle events

The SDK synthesizes events for the WebView’s own lifecycle and for the session mirror. It delivers them through addEventCallback and addSdkEventCallback, alongside the runtime’s events:

Key	Fires when
`ada.webview.loaded`	The WebView finishes loading its page. The payload includes the loaded `url`.
`ada.webview.loadFailed`	The initial load fails: a main-frame resource error, an HTTP status of 400 or higher, a load timeout, or a URL build failure. The payload includes `url`, `code`, `statusCode`, and `error`. `webViewLoadingErrorCallback` and `webViewErrorCallback` also fire.
`ada.webview.subresourceLoadFailed`	A resource inside the page fails to load after the main document: a subresource error or an HTTP status of 400 or higher. Reported once per URL per page load. The payload includes `url`, `code`, `statusCode`, and `error`. The error callbacks do not fire, because the main frame is intact.
`ada.webview.mainDocumentLost`	The main frame leaves the trusted Ada document, so the chat bridge stops working. The payload includes `url` and `recovering`. `recovering` is `true` when the SDK reloads the trusted document. `webViewLoadingErrorCallback` and `webViewErrorCallback` also fire.
`ada.sessionMirror.diagnostic`	The SDK cannot complete a session mirror operation. The payload includes one `reason` string and no session data. The SDK reports each reason once per loaded document, except `adapter-removeItem-failed`, which it reports every time. Reasons: `adapter-getItem-failed`, `adapter-removeItem-failed`, `adapter-setItem-failed`, `entries-not-allowlisted`, `legacy-rollout-unresolved`, `origin-mismatch`, `scope-mismatch`.

Headless mode

Headless mode runs the Messaging runtime without visible conversation UI. Your app receives conversation events and sends messages through native code. Use it to build native surfaces such as unread badges, notification banners, or a custom composer.

Two pieces combine into headless operation:

The headless setting tells the runtime to suppress its default UI. The runtime still boots, connects, and emits events.
The AdaMessagingView.headless(context, settings) factory constructs the view without a layout tree. The view starts loading immediately instead of waiting for window attachment.

You can also place a normal AdaMessagingView in your layout at zero size. The factory exists so you do not have to.

The headless factory

AdaMessagingView.headless(context: Context, settings: Settings): AdaMessagingView

Builds a view that runs without joining the layout tree. The factory forces headless = true on the settings it receives. It requires webSdk(AdaWebSdk.Messaging), and throws IllegalArgumentException when the settings target the Legacy runtime.

Example: drive a native unread badge

Kotlin

val settings = AdaMessagingView.Settings.Builder("my-handle")
    .webSdk(AdaWebSdk.Messaging)
    .enableProgrammaticControl(true)
    .identityToken(tokenFromYourBackend)
    .build()
val ada = AdaMessagingView.headless(context, settings)
ada.addEventCallback("ada:message:received") { event ->
    unreadBadge.increment()
}
ada.addEventCallback("ada:message:sent") { event ->
    unreadBadge.clear()
}
ada.sendMessage("I need help with my order")

sendMessage calls queue until the runtime reports sdk.ready, so you can call it right after the factory returns.

Constraints

Messaging runtime only. The factory rejects AdaWebSdk.Legacy with an IllegalArgumentException.
sendMessage needs programmatic control. The runtime rejects the send with ProgrammaticControlNotEnabled unless you set enableProgrammaticControl(true).
No background execution. The WebView runs only while your process lives. It is not a push channel and not a background service. Use setDeviceToken and push notifications for delivery while your app is closed.
One conversation session per view. Do not create a headless view and a visible view for the same end user at the same time. Attach the headless view later if you need UI.

Lifecycle you still own

An unattached WebView does not receive lifecycle callbacks from the framework. Forward them yourself:

Call ada.onResume() when your owning screen or app comes to the foreground.
Call ada.onPause() when it leaves the foreground. This pauses timers and reduces battery use.
Call ada.destroy() when you are done with the view. Remove your event callbacks first.

Tie these calls to a LifecycleObserver on the owning activity, fragment, or process lifecycle.

Showing UI later

A headless view is a real AdaMessagingView. Add it to a layout with nonzero size to show the conversation:

Kotlin

container.addView(ada, MATCH_PARENT, MATCH_PARENT)

The in-flight session continues, and the view does not reload on attachment. The runtime keeps its headless flag, so start a non-headless view when you need Ada’s own conversation UI.

AdaMessagingActivity and AdaMessagingDialog

To call actions on AdaMessagingActivity, call getAdaView() to obtain the AdaMessagingView instance. The method is public, so any code that holds the activity instance can call it. It is available from onCreate onward. For example, from a subclass:

Kotlin

class MyCustomActivity : AdaMessagingActivity() {
    override fun onResume() {
        super.onResume()
        val adaView = getAdaView()
        adaView.setMetaFields(
            AdaMessagingView.MetaFields.Builder()
                .setField("name", "John"),
        )
    }
}

AdaMessagingDialog forwards the common actions directly: clearPersistedState, deleteHistory, downloadTranscript, reset, sendMessage, setDeviceToken, setLanguage, setMetaFields, and setSensitiveMetaFields, plus the subscription methods addEventCallback, removeEventCallbacks, addSdkEventCallback, and removeSdkEventCallback. Obtain the dialog instance from the fragment manager:

Kotlin

val adaDialog = supportFragmentManager
    .findFragmentByTag(AdaMessagingDialog.TAG) as AdaMessagingDialog
adaDialog.setMetaFields(
    AdaMessagingView.MetaFields.Builder()
        .setField("name", "John"),
)
adaDialog.reset()

You can register event callbacks on the dialog before it is shown. The dialog buffers them and attaches them when its view is created. Call the other forwarded actions only after the dialog is shown.

Session persistence

From version 1.2.0, session state persists across an app force-quit. Session state includes the end-user token and any active live agent handoff context. If an end user force-quits the app during a conversation or a live agent handoff, the conversation continues when they reopen the app.

The web runtime stores session state in the WebView’s localStorage, as before. From version 1.2.0, the SDK also stores a session mirror in app-private SharedPreferences. On Android, localStorage is not guaranteed to survive a force-quit. When that happens, the SDK restores the session state from the session mirror.

The session mirror is app-private, and the SDK stores the values in plain form. The SDK never persists identity tokens to disk.

The SDK ships backup-exclusion rules as the resources @xml/ada_messaging_backup_rules and @xml/ada_messaging_data_extraction_rules. The SDK sets no android:fullBackupContent or android:dataExtractionRules attribute for them. The manifest merger treats a library value for those attributes as a conflict with an app that declares its own. That conflict fails the app build.

Your app must wire the exclusion itself. If your app declares no backup rules, reference the SDK rule resources on your <application> element:

XML

<application
    android:fullBackupContent="@xml/ada_messaging_backup_rules"
    android:dataExtractionRules="@xml/ada_messaging_data_extraction_rules">

If your app has its own rule files, add the same exclusion to them instead:

XML

<!-- fullBackupContent (pre-API 31) -->
<exclude domain="sharedpref" path="cx.ada.messaging.session-mirror.xml" />
<!-- dataExtractionRules (API 31+), in both <cloud-backup> and <device-transfer> -->
<exclude domain="sharedpref" path="cx.ada.messaging.session-mirror.xml" />

This step excludes the session mirror from Android Auto Backup and device transfer. Without this step, a device backup can copy session state to the cloud and restore it on another device.

Session persistence follows your AI Agent’s persistence setting:

The normal persistence mode writes the session mirror. The SDK stores session state natively.
The session and private persistence modes clear the session mirror. The SDK writes no session mirror in these modes.

If you supply an identityToken at initialization or on reset, the token takes precedence. The SDK performs the identity exchange first, and the resolved session replaces any previously persisted session state.

When an end user signs out of your app, call reset, deleteHistory, or clearPersistedState. Sessions now survive app restarts. If you skip this step, the next user of the device can resume the previous user’s conversation.

The native side also caches a small allowlist of non-sensitive branding state, with a 10 minute expiry, to smooth the next launch. clearPersistedState removes both the branding cache and the session mirror.

Types

AdaEnvironment

Sealed class that selects the Ada deployment environment. Pass it to environment.

Value	Description
`AdaEnvironment.Production`	Ada’s production environment. The default.
`AdaEnvironment.Preprod(branch)`	Ada’s pre-production environment, for validation the Ada team directs.
`AdaEnvironment.Local(port, host)`	A local development server, for SDK development.

AdaWebSdk

Enum that selects the web runtime. Pass it to webSdk.

Value	Description
`AdaWebSdk.Legacy`	The existing Chat runtime. The default.
`AdaWebSdk.Messaging`	The next-generation Messaging runtime.

AdaWebViewError

Sealed class delivered to webViewErrorCallback.

Case	Description
`BridgeError(error)`	The native bridge reported an error before the runtime became ready.
`HttpError(url, statusCode)`	The main document responded with an HTTP error status.
`LoadFailed(url, errorCode, description)`	The main document failed to load. `url` is `null` when the SDK could not build the WebView URL.
`Timeout(timeoutMillis)`	The page did not finish loading within `loadTimeoutMillis`.

Event

Data class delivered to addEventCallback subscribers.

Field	Type	Description
`chatterTranscript`	`String?`	The conversation transcript, when the event carries one.
`eventName`	`String?`	The event key, for example `ada:message:received`.
`userData`	`JSONObject?`	Event-specific payload data.

MetaFields.Builder

Builder for metaFields and sensitiveMetaFields values. setField(key, value) accepts String, Boolean, Int, Long, Float, and Double values.

Kotlin

AdaMessagingView.MetaFields.Builder()
    .setField("name", "John")
    .setField("age", 20)
    .setField("authorized", true)