SDK API Reference

Use the React Native SDK settings, actions, and events to customize the behavior of your AI Agent.

Settings

AdaMessagingView takes the following props. Only handle is required.

appUrl

appUrl?: string;

Overrides the app frame URL that the Messaging runtime mounts.

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 or simulator, 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 or simulator reaches the tunnel origin directly, so no port forwarding is needed.

The exception is the local asset-server environment (environment: { type: "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. On Android, 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:

1
adb reverse tcp:5173 tcp:5173

The SDK injects the value into the WebView document through an injected configuration object, never through a URL. Unlike identityToken, which the runtime reads once, the value is delivered again on every document load. Changing the value reloads the WebView. See Custom apps. Requires the Messaging runtime (webSdk="messaging").

cluster

cluster?: string;

Specifies the region your AI Agent runs on. Pass either a short region name (for example, maple or us2) or a full cluster domain. Short names resolve to <name>.ada.support. Defaults to ada.support.

deviceToken

deviceToken?: string;

Push notification device token. The SDK sends it automatically once the runtime is ready.

domain

domain?: string;

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

embedVersion

embedVersion?: string;

Pins the remote legacy host page to a specific legacy web build for pre-release verification. Rendered as the ?__ada-embed-version=<sha> query parameter. Leave unset for the stable rollout. Ignored when webSdk is not "legacy".

endConversationCallback

endConversationCallback?: (event: unknown) => void;

Called when a conversation ends.

environment

1
environment?:
2
  | { type: "production" }
3
  | { type: "preprod"; branch?: string }
4
  | { type: "local"; port?: number; host?: string }
5
  | { type: "custom"; assetsOrigin: string };

Selects which Ada web-hosting environment the WebView loads and the matching origin allowlists. When provided, environment takes precedence over cluster for asset resolution. Leave unset for production.

eventCallbacks

eventCallbacks?: Record<string, (event: unknown) => void>;

Dictionary of event callbacks keyed by event name. Supports "*" as a wildcard to receive all events.

greeting

greeting?: string;

Specifies a greeting response ID to trigger on load. This is useful for setting view-specific greetings across your app.

handle

handle: string;

The handle for your AI Agent. This is a required field.

headless

headless?: boolean;

When set to true, the SDK runs the Ada runtime without rendering its chat UI. The WebView stays mounted but hidden and non-interactive: it renders as an absolute-positioned, transparent 1×1 view with pointer events and accessibility disabled. onEvent, onStateCache, and every action keep working, so you can drive a fully native UI, such as an unread badge fed by message events.

Unmounting the component ends the live session. Pass the last onStateCache snapshot back as initialState to rehydrate on the next mount.

Headless requires the Messaging runtime (webSdk="messaging"). The remote legacy host page ignores it. See Headless mode for a complete example.

identityToken

identityToken?: string;

Short-lived, single-use identity token minted by your backend via POST /v2/auth/tokens/. Use it to start the session as a known user.

The SDK injects the token into the WebView document before content loads. The token is never placed in a URL. The runtime reads the injected value once per document load and deletes it immediately. Blank or whitespace-only values are treated as absent.

Provide the token before mounting the view. A value set after mount only applies when the WebView reloads, and a reload needs a freshly minted token because tokens are single-use. After the runtime becomes ready, the SDK never delivers a consumed token again on later reloads. Set a newly minted token to authenticate again. Requires the Messaging runtime (webSdk="messaging").

initialState

initialState?: Record<string, unknown> | null;

Previously cached state snapshot to inject before the page loads. When provided, the chat UI renders immediately without a loading state. Capture snapshots with onStateCache.

The SDK filters the value to the allowlisted keys in PERSISTABLE_STATE_KEYS before injection, and discards the whole snapshot when its __ada_cached_at__ timestamp is older than 10 minutes. See State persistence exports.

language

language?: string;

Takes in a language code to programmatically set the AI Agent language. You must first turn on languages in your Ada dashboard.

loadTimeoutMs

loadTimeoutMs?: number;

The maximum time in milliseconds the initial WebView load may take. Defaults to 30000, matching the iOS webViewTimeout and Android loadTimeoutMillis defaults. When the timeout elapses first, the component emits the ada.webview.loadFailed event and calls onError. Pass 0 or a negative value to disable the timeout.

metaFields

metaFields?: Record<string, string | number | boolean | null>;

Use metaFields to pass information about an end user to Ada on initialization. This can be useful for tracking information about your end users, as well as personalizing their experience.

1
metaFields={{
2
  name: "Some name",
3
  age: 30
4
}}

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

onError

onError?: (error: string) => void;

Called when an error occurs inside the WebView, including load failures and runtime errors reported by the SDK.

onEvent

onEvent?: (key: string, data: unknown) => void;

Called whenever the SDK publishes an event, and for WebView lifecycle events. Subscribe to specific keys for analytics or routing. See Events for the available keys.

1
onEvent={(key, data) => {
2
  if (key === "ada:end_conversation") {
3
    console.log("Conversation ended", data);
4
  }
5
}}

onReady

onReady?: () => void;

Called when the SDK has finished initializing and is ready to accept commands. Use it to send sensitive metadata and device tokens through the ref.

onStateCache

onStateCache?: (state: Record<string, unknown>) => void;

Called when the runtime sends a state cache snapshot. Store the snapshot and pass it back as initialState on the next mount to remove the reload spinner after the WebView restarts.

Before your callback runs, the SDK reduces the snapshot to the allowlisted keys in PERSISTABLE_STATE_KEYS and stamps it with __ada_cached_at__. Session credentials and conversation content never reach your code, and the delivered snapshot is safe to persist as is. It matches what the iOS and Android SDKs cache natively. See State persistence exports.

preprodDemoToken

preprodDemoToken?: string;

Time-bound demo access token for Messaging preprod assets. Applied only when environment.type is "preprod" and webSdk is "messaging". Leave unset for production, local, and legacy flows.

sensitiveMetaFields

sensitiveMetaFields?: Record<string, string | number | boolean | null>;

Sensitive metadata to pass to the AI Agent after initialization. The SDK sends it automatically once the runtime is ready.

style

style?: StyleProp<ViewStyle>;

Additional style overrides for the container view. When headless is set, the hidden styling is applied after style and always wins.

styles

styles?: string | Record<string, string>;

Style overrides for the web runtime. The accepted shape depends on the runtime:

• Messaging runtime: pass an object of theme style tokens, for example styles={{ tintColor: "#520497" }}. The runtime honors tintColor only today, and ignores unsupported keys. The string form is never sent to the Messaging runtime.
• Legacy runtime: pass a CSS style override string.

Empty values are omitted.

thirdPartyCookiesEnabled

thirdPartyCookiesEnabled?: boolean;

Enables third-party cookies in the WebView. Android only.

version

version?: string;

Pins the remote legacy host page to a specific legacy chat build for pre-release verification. Rendered as the ?__ada-chat-version=<sha> query parameter. Leave unset for the stable rollout. Ignored when webSdk is not "legacy".

webSdk

webSdk?: "messaging" | "legacy";

Selects which web runtime boots inside the WebView. Defaults to "legacy" so package upgrades do not change end-user behavior before you intentionally cut over. Set "messaging" to run the Messaging runtime.

The headless and identityToken settings and the sendMessage action require the Messaging runtime.

zdChatterAuthCallback

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

Callback for Zendesk authentication. When the SDK requests a Zendesk auth token, this callback is invoked with a resolver function. Request a fresh JWT token from your API, then call the resolver with it.

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

Actions

Call actions on the AdaMessagingView ref. This lets you control the AI Agent without re-rendering the component. Commands sent before the runtime is ready are queued, then flushed automatically when it becomes ready.

1
import { useRef } from "react";
2
import {
3
  AdaMessagingView,
4
  type AdaMessagingViewHandle,
5
} from "@ada-cx/messaging-react-native";
6
7
function MyComponent() {
8
  const adaRef = useRef<AdaMessagingViewHandle>(null);
9
10
  return <AdaMessagingView ref={adaRef} handle="my-company" webSdk="messaging" />;
11
}

deleteHistory

deleteHistory(): void;

Deletes the conversation history and resets the session.

1
adaRef.current?.deleteHistory();

reset

reset(opts?): void;

Starts a new session and refreshes the chat. reset can take an optional object that changes greeting, language, metaFields, and sensitiveMetaFields for the new session. Pass resetChatHistory: false to keep the existing history.

1
adaRef.current?.reset();
2
3
// With options
4
adaRef.current?.reset({
5
  language: "fr",
6
  metaFields: { plan: "pro" },
7
  resetChatHistory: true,
8
});

sendMessage

sendMessage(body: string): void;

Sends a message into the conversation on behalf of the end user. Pair it with headless and onEvent to drive a fully native chat UI.

1
adaRef.current?.sendMessage("Where is my order?");

setDeviceToken

setDeviceToken(token: string): void;

Registers a push notification device token with Ada. Call it in onReady.

1
adaRef.current?.setDeviceToken("push-token");

setLanguage

setLanguage(language: string): void;

Changes the display language at runtime without resetting the session. Language codes use the lowercase, two-letter ISO 639-1 language format.

1
adaRef.current?.setLanguage("fr");

setMetaFields

setMetaFields(fields: Record<string, string | number | boolean | null>): void;

Updates metaFields without resetting the session. This is useful if you need to update end-user data after the Agent has already launched.

1
adaRef.current?.setMetaFields({
2
  name: "Some name",
3
  age: 30,
4
});

setSensitiveMetaFields

setSensitiveMetaFields(fields: Record<string, string | number | boolean | null>): void;

Updates sensitive metadata without resetting the session. This works like setMetaFields, but provides an added layer of security. Call it in onReady.

1
adaRef.current?.setSensitiveMetaFields({
2
  token: "your_jwt_token",
3
});

Events

Subscribe to events through the onEvent prop. The callback receives the event key and an event-specific data payload.

SDK events

With the Messaging runtime, onEvent receives every event the SDK publishes. Common keys include:

WebView lifecycle events

The component also reports its own lifecycle through onEvent:

State persistence exports

The package exports the pieces of the state persistence contract described in Session lifecycle and state restoration.

PERSISTABLE_STATE_KEYS

PERSISTABLE_STATE_KEYS: readonly string[]

The allowlist of snapshot keys the SDK keeps: advancedColorsEnabled, allowedProtocols, button, chatEnabled, fallbackUi, features, intro, proactiveConversations, textOverAccentColor, tintColor, and __ada_cached_at__. It matches the allowlist the iOS and Android SDKs persist natively.

STATE_CACHE_TTL_MS

STATE_CACHE_TTL_MS = 600000

The snapshot expiry in milliseconds (10 minutes). An initialState snapshot with an older __ada_cached_at__ stamp is discarded instead of injected.

toPersistableStateSnapshot

toPersistableStateSnapshot(state: Record<string, unknown>): Record<string, unknown>

Reduces a snapshot to the allowlisted keys, and stamps __ada_cached_at__ when the stamp is missing. onStateCache already applies this filter. Use it to sanitize snapshots that earlier package versions persisted unfiltered, before you pass them as initialState.