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

# Programmatic and headless control for the Web Chat SDK

Customizing Ada chat on a website previously meant either using the default chat drawer as-is or building a server-side integration on the Conversations API. The Web Chat SDK now adds methods and events for driving a conversation directly from a web page's JavaScript, plus a headless mode that connects to the AI Agent without rendering the built-in chat button or drawer.

A host page can use these to build its own chat surface — such as a search bar, sidebar, inline form helper, or command palette — or to let in-page scripts and browser-side tools read and send messages on behalf of the end user. All of these run against the same AI Agent, handoffs, and live-agent routing as the default chat drawer, with no server-side integration required. For help deciding between the Web Chat SDK, native SDKs, and the Conversations API, see [Choosing an integration](/chat/introduction/choosing-an-integration).

## New actions

New methods on the `adaEmbed` object read and drive the active conversation:

* `sendMessage` — send a free-text message to the AI Agent on behalf of the end user.
* `getConversation`, `getMessages`, and `getMetaFields` — read the active conversation, its in-memory messages, and the merged metafields.
* `setComposerText` — pre-fill the built-in composer input. Requires the `enableProgrammaticControl` setting.
* `setDelegate` — register a `beforeSend` hook that can transform or cancel messages sent through `sendMessage`.
* `isOpen` — check whether the chat drawer is currently open.

## New events

`subscribeEvent` now emits lifecycle events for the conversation:

* `ada:ready` when the SDK has loaded.
* `ada:message:sent` and `ada:message:received` for each message.
* `ada:typing:start` and `ada:typing:stop` for agent typing state.
* `ada:connection:change` and `ada:conversation:change` for connection and conversation transitions.

## Headless mode

The new `headless` setting connects Chat in the background without rendering the default chat button or drawer. Use it when the page renders its own chat UI and drives the conversation through `sendMessage`, `getMessages`, and `subscribeEvent`. Methods that act on the built-in UI, such as `setComposerText`, are not available in headless mode.

Headless sessions run with no visual indicator, so enabling the setting is a trust decision for the host page.

## Availability

These additions apply to the Web Chat SDK. iOS and React Native references are unchanged.

## Get started

* [Web Chat SDK API reference](/chat/web/sdk-api-reference)
* [`headless` setting](/chat/web/sdk-api-reference#headless)
* [Actions](/chat/web/sdk-api-reference#actions) and [`subscribeEvent`](/chat/web/sdk-api-reference#subscribeevent)