State and events

Your handle’s Allowed websites list controls custom apps. In your Ada dashboard, go to Channels > Chat and add your app’s origin. Until the list allows your origin, a configured appUrl is dropped with a console warning and Ada’s default app mounts. Local development needs no entry when both your app and the embedding page run on loopback hosts. See Local development.

The bridge contract has two halves. Core publishes a display state object (AppDisplayState) that your app renders from. Your app sends typed events (AppEvents) back. The full typed contract ships in the npm package, so treat the package’s TypeScript declarations as the shape reference.

This page documents when each customer-relevant key updates, which events are supported, and which surfaces are reserved. Prefer the operations helpers over raw events; nearly every supported event has one.

Update cadence

Core coalesces state publication:

At most one state update per microtask. A synchronous batch of internal changes produces one update, not one per change.
The update is skipped entirely when the derived state is unchanged.
Unchanged keys keep their reference identity across updates. State crosses the frame boundary by structured clone, so the bridge client restores the previous reference for each structurally unchanged key before it notifies. Object.is per key is therefore a sound change detector, which is what subscribeKey uses.
An object key’s identity changes exactly when its content does. For chat.messages, that is every streaming delta: the growing message body changes the array’s content each time.

One consequence: a key that flips on and off inside one synchronous batch is invisible. chat.isSending behaves this way; see below.

Display state

The tables below list the documented keys and the condition that updates each one. Keys not listed here are reserved.

Conversation keys

Key	Updates when
`chat.answeredInteractiveIds`	The end user answers an interactive block, or a later user message in the same conversation supersedes one. The set survives a reload. Filter interactive rows on it before enabling them.
`chat.canLoadMore`	A history load reports whether older pages remain.
`chat.composerText`	Core sets or clears its owned composer draft. Apply it only when its `revision` changes. Core clears it the moment a send consumes it.
`chat.conversationGeneration`	A conversation or reset boundary occurs; the counter is monotonic.
`chat.conversationId`	The conversation is established server-side. The id arrives asynchronously over the realtime channel, not with the send response, and is null before then.
`chat.error`	A send fails (this also clears the sending and generating flags). Cleared only by `dismissError`.
`chat.error.seq`	Core sets `chat.error` — the counter advances even when the new text is identical to the current one, which `chat.error` alone cannot surface. Send handles fall back to its advance on cores that predate `chat.error.clientKey`.
`chat.error.clientKey`	Core sets `chat.error`. Carries the failing send’s `tempMessageUuid` when the error belongs to one keyed send, and `null` otherwise. Send handles reject only when it matches their own key.
`chat.isConversationActive`	The server’s conversation-active verdict changes.
`chat.isGenerating`	True from the moment an optimistic user message lands until the reply arrives or the send fails. This, not `chat.isSending`, is the “a reply is coming” signal.
`chat.isSending`	A send starts or completes. On a normal AI Agent send, both happen in one synchronous batch, so the true value is effectively never observable. It stays true only across a genuine failure gap.
`chat.lastReadCursor`	A read report commits (after the 400 ms `markRead` debounce), or the persisted watermark rehydrates on reload. Not monotonic across tabs by design.
`chat.loadingPreviousMessages`	A history page load starts or finishes.
`chat.messages`	Any append, upsert, streaming delta, reaction, or history load. An optimistic user row appears immediately on send; its durable echo later reconciles in place, swapping `id` while carrying `clientKey` forward.
`chat.playbookStepExecuting`	A Playbook step starts or finishes running server-side. While true, the composer must refuse to send: free text would be consumed as the step’s input.
`chat.recentMessagesLoadSeq`	Restored or baseline history (re)loads; the counter increments. Returns to 0 when the chat is cleared. Drives the one-shot “land at the bottom of restored history” behavior.
`conversation.stateData.capture`	The AI Agent blocks on a capture field. `isSubmitting` flips true when a submit leaves the browser and false when it resolves; `validationErrorMessage` carries the verdict. An accepted value removes the whole object. `lastSubmitFailure` records a submit that failed or was dropped without a server verdict, keyed by the submitter’s own `submitId`.
`conversation.stateData.listSelection`	A list-selection block becomes active or resolves. Carries the `dataId` and cancel response that submit and cancel need.

Agent and typing keys

Key	Updates when
`agent.activeAgent`	An agent becomes active, changes, or leaves. Prefer a message’s own `agentInfo` when naming its sender: restored history outlives an agent’s session.
`liveAgent.inLiveChat`	A live-agent handoff connects or ends.
`liveAgent.inPending`	A handoff request enters or leaves the pending state.
`liveAgent.queueCancelPending`	A queue-cancel request (`ui.queueCancel.request`) goes in flight or resolves. Disable your cancel affordance while true.
`liveAgent.queuePosition`	The end user’s queue position changes.
`ui.botTyping.visible`	The AI Agent’s own typing indicator turns on or off (a request is in flight).
`ui.typingIndicator.visible`	Core’s combined typing verdict changes: the AI Agent is typing, or any agent is. Drive one indicator from this, or use the `isAgentTyping` helper.

Survey and End Chat keys

The survey keys implement two correlation patterns. Success and failure each carry a triple (a signal plus a survey type plus a conversation id), and eligibility carries a latched sequence. The operations helpers implement both patterns; the raw keys are documented for completeness.

Key	Updates when
`csat.endChatEligibility.seq`	An eligibility answer arrives; the counter increments. There is no request id: latch the value before asking and treat yourself as pending until it advances.
`csat.endChatEligibility.status`	An eligibility check starts (`loading`) or answers (`ready`).
`csat.endChatEligible`	The eligibility answer arrives.
`csat.endChatSurveyTarget`	The eligibility answer names which survey End Chat should present.
`csat.submitError`	A survey submit fails, or a score is invalid for its scale. Cleared to null at the start of every non-partial submit.
`csat.submitError.seq`	Core sets `csat.submitError` to a message. The counter advances even when the new text is identical, which the text alone cannot surface. Correlate error verdicts on its advance plus the type and conversation match.
`csat.submitErrorConversationId`	Together with `csat.submitError`; scopes the failure.
`csat.submitErrorSurveyType`	Together with `csat.submitError`; scopes the failure.
`csat.submitSuccess.conversationId`	Together with the success counter; scopes the success.
`csat.submitSuccess.seq`	A terminal survey submit succeeds; the counter increments. A `partial` submit does not bump it. Match survey type and conversation id when it advances; type alone lets a late answer from a dead conversation close the wrong survey.
`csat.submitSuccess.surveyType`	Together with the success counter; scopes the success.
`endChat.canEnd`	Whether End Chat is offered changes: the conversation has not ended, the end user has sent in it, and a conversation id exists. Gates the header close affordance.

Transcript and file keys

Key	Updates when
`file.isUploading`	A live-agent upload goes in flight or resolves. Core can reject a selection and report an error without ever setting this true, so watch `file.uploadError` too.
`file.transfer`	Upload progress advances.
`file.uploadError`	An upload fails or its error is dismissed.
`transcript.download.status`	A transcript download moves `idle` to `pending` to `success` or `error`. A request that core drops during a host-driven reset skips `pending` and lands on `error` directly.
`transcript.download.status.seq`	Every `transcript.download.status` write; the counter increments. Correlate on its advance to a terminal status, not on the standing text.
`transcript.email.status`	Same lifecycle, for the email-transcript request.
`transcript.email.status.seq`	Same contract as `transcript.download.status.seq`, for the email request.
`transcript.email.conflict.email`	Core rejects an `emailTranscript` call for a different address while one is in flight. This key carries the rejected address, so only that caller’s promise rejects. The in-flight request is not affected.
`transcript.email.conflict.seq`	Every `transcript.email.conflict.email` write; the counter increments.

Configuration and preference keys

config.* keys carry the AI Agent’s resolved configuration and theming: name, avatar, colors, languages, and feature toggles. They change rarely after startup. Three preference keys respond to the settings helpers:

Key	Updates when
`appearance.userTextSize`	The end user’s text-size override changes (`setTextSize`); core persists it.
`appearance.userTheme`	The end user’s theme override changes (`setTheme`); core persists it.

The host page’s Web Notification permission is mirrored into the state under a legacy-named prefix. It updates when the SDK host reports the permission, and after requestNotificationPermission resolves the prompt. Permission is per-origin, so your frame’s own value is not the governing one:

1 client.subscribeKey("chatter.notificationPermission", (permission) => {
2   // "default" | "granted" | "denied"
3 });

Connectivity

outage.connectivityLost is the sanctioned connectivity signal. It is core’s own verdict, and it updates when core decides connectivity was lost or restored. Use it to disable send UI or to warn before End Chat. The isConnectivityLost helper reads it.

Do not substitute other signals:

navigator.onLine reports false positives on VPN and virtual-adapter transitions. Ada’s reference app explicitly refuses it for this reason.
Other outage.* keys are dismissible banner state and backoff internals, and they are reserved. A dismissed banner can read as recovered while the outage continues.

Events

Nearly every supported event has an operations helper that carries its guards and correlation logic. Send raw events only for the ones marked “send directly”, or when you need something a helper does not expose.

Lifecycle events

Event	Operations helper	Notes
`app.error.report`	`reportAppError`	Renders the fallback UI and records telemetry.
`app.initialize`	none (send directly)	The required mount handshake. Send it within 15 seconds of frame load, or core unmounts your frame.
`app.reset`	`resetApp`
`app.startNewConversation`	`startNewConversation`	The helper adds the cooldown latch.

Conversation events

Event	Operations helper	Notes
`capture.cancel`	`cancelCapture`	The helper supplies the block’s cancel response and `dataId`.
`capture.submit`	`submitCapture`	The helper supplies the `dataId` and correlates the verdict.
`chat.error.dismiss`	`dismissError`	Clears `chat.error` in core.
`chat.link.click`	`reportLinkClick`
`chat.logs.loadMore`	`loadOlderMessages`	The helper adds the in-flight guard.
`chat.message.reaction.add`	`addReaction`
`chat.message.retry`	`retryMessage`	Core reads only the message id.
`chat.message.send`	`sendMessage`	When `tempMessageUuid` is an RFC 4122 uuid, core seeds the optimistic message’s `clientKey` from it, so the sender can find its own send in `chat.messages`. `messageType: "secret"` masks the send, and no correlatable row exists.
`chat.messages.read`	`markRead`	The helper adds the debounce, the monotonic watermark, and the per-conversation reset.
`chat.option.select`	`selectOption`
`chat.quickReply.select`	`selectQuickReply`
`chat.selectableList.submit`	`submitListSelection`	The helper supplies the `dataId`.
`listSelection.cancel`	`cancelListSelection`	Core drops a cancel without a response id; the helper guards this.

Survey and End Chat events

Event	Operations helper	Notes
`csat.checkEndChatEligibility`	`checkEndChatEligibility`	The helper latches the sequence and resolves on its advance.
`csat.shown`	`trackCsatShown`	Fire-and-forget analytics.
`csat.submit`	`submitCsat`	Pass `conversationId` for in-transcript survey rows; omit it for End Chat and proactive flows.
`endChat.skipCsat`	`skipCsatAndEndChat`

Preference, file, and chrome events

Event	Operations helper	Notes
`appearance.setTextSize`	`setTextSize`
`appearance.setTheme`	`setTheme`
`file.upload.errorDismiss`	`startFileUpload` handle’s `dismissError()`
`file.upload.retry`	`startFileUpload` handle’s `retry()`	Must replay the exact retained `{ file, uploadId }` pair.
`file.upload.start`	`startFileUpload`
`outage.retry`	`retryAfterOutage`
`settings.alertSound.toggle`	`setAlertSound`
`settings.language.change`	`setLanguage`
`settings.notifications.requestPermission`	`requestNotificationPermission`
`settings.transcript.download.request`	`downloadTranscript`
`settings.transcript.email.send`	`emailTranscript`
`ui.closeButton.click`	`close`
`ui.composer.textChanged`	`notifyComposerChanged`	Payload-free by contract; the helper suppresses it in secret mode.
`ui.hostViewport.set`	`setHostViewportExpanded`
`ui.minimizeButton.click`	`minimize`
`ui.queueCancel.request`	none (send directly)	Leaves a live-chat queue. Payload-free. Gate the affordance on `liveAgent.inPending`, and disable it while `liveAgent.queueCancelPending` is true.
`ui.secretMessage.toggle`	`toggleSecretMessage`
`ui.toast.dismiss`	`dismissToast`

Reserved surfaces

Any key or event this page does not list is reserved: it exists for Ada’s own app, native SDKs, or internal integrations, and it can change or disappear without notice. Do not build on reserved surfaces. This includes:

security.* keys and events (challenge state and control).
voice.* keys and events. These are annotated as reserved in the package types.
zendesk.* and zendeskMessaging.* keys and events (handoff SDK control).
liveAgent.* events (liveAgent.handoff.request, liveAgent.message.send, and the rest). Ada’s own app never sends them; handoffs are driven by core. To leave a queue, send ui.queueCancel.request. The documented liveAgent.* state keys above are read-only signals.
saml.* keys.
outage.* keys other than outage.connectivityLost, and any backoff internals.
image.print.request.

The reserved surfaces still appear in the package’s TypeScript declarations, because the types mirror the full wire contract. Presence in the types is not a support commitment; this page is.