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

# Choosing an integration

The Messaging SDK can be embedded and driven in several ways. This page describes the available integrations and when to use each, so the right approach is chosen before development begins.

## Quick comparison

| Integration                              | Runs in                   | Code required                             | Use when                                                                                                        |
| ---------------------------------------- | ------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Default embed (loader script)            | Web browser               | None beyond the script tag                | An existing Chat SDK script tag keeps working unchanged. Deprecated for new installations.                      |
| Module-script import                     | Web browser               | A `<script type="module">` block          | A new installation without a bundler needs the launcher and drawer, or the page controls its own bootstrapping. |
| `@ada-cx/messaging-sdk` (npm)            | Web browser               | An npm install and one import             | The site is built with a bundler and wants TypeScript types, test mocks, and the always-current runtime.        |
| Headless + programmatic control          | Web browser or mobile app | SDK method calls and event subscriptions  | Your own UI renders the conversation, or in-page code sends and reads messages.                                 |
| Custom apps                              | Web browser or mobile app | A hosted app + `@ada-cx/messaging-bridge` | You replace the built-in conversation UI with an app you host inside Ada's frame chain.                         |
| Mobile SDKs (iOS, Android, React Native) | Mobile app                | Native integration                        | The AI Agent is embedded in a mobile application.                                                               |
| Conversations API                        | Your server               | Server-side integration                   | The integration runs on a server, or on a channel Ada does not render.                                          |

## Default embed

The default embed is the standard experience: a launcher button and a chat drawer. If your site already loads Ada through a script tag, no code change is required. The loader keeps the `window.adaEmbed` global, and `window.adaSettings` remains fully supported.

Use it when:

* An existing Chat SDK integration should keep working as is.

For new installations, the globals are deprecated. Start with the [module-script import](#module-script-import) or the [npm loader package](#npm-loader-package) instead; both render the same launcher and drawer. See [Security best practices](/messaging/web/security-best-practices#prefer-module-imports-for-new-installations) for the reasoning.

See [Migrate from the Chat SDK web script](/messaging/web/getting-started#migrate-from-the-chat-sdk-web-script).

## Module-script import

Pages that control their own bootstrapping can import the hosted SDK entry directly:

```html
<script type="module">
  import { createAdaEmbedInterface } from "https://messaging-assets.ada.support/sdk.js";

  const adaEmbed = createAdaEmbedInterface();
  await adaEmbed.start({ handle: "<your-handle>" });
</script>
```

The `adaEmbed` reference stays private to the module, so other scripts on the page cannot reach it. See [Security best practices](/messaging/web/security-best-practices#keep-the-client-in-a-private-scope).

Use it when:

* You are building a new installation without a bundler.
* You want explicit control over when the AI Agent starts.

See the [Web SDK getting started guide](/messaging/web/getting-started#embed-with-a-module-script).

## npm loader package

[`@ada-cx/messaging-sdk`](https://www.npmjs.com/package/@ada-cx/messaging-sdk) is the npm integration for bundled applications. It provides TypeScript types for the full SDK surface, an in-memory mock for unit tests, and a thin loader.

> **Note**
>
> [`@ada-cx/messaging-sdk`](https://www.npmjs.com/package/@ada-cx/messaging-sdk) is live on npm. Install the latest version.

The package never contains the SDK runtime. The loader imports the runtime from Ada's CDN at page load, so every page always receives the current rollout version. The npm version covers only the loader, the types, and the mocks. It never pins the runtime. This is the same model as `@stripe/stripe-js`.

Use it when:

* The site is built with a bundler and wants typed, testable access to the SDK.
* You want CDN delivery of the runtime while keeping an npm workflow.

To validate a specific runtime build before it rolls out, use the [`?ada-messaging-version` query parameter](/messaging/web/getting-started#validate-a-specific-runtime-version). See [Install from npm](/messaging/web/getting-started#install-from-npm) for the quick start.

## Headless and programmatic control

Use headless mode when your website or native app renders the UI and drives conversations through SDK methods and events. The SDK connects to the AI Agent without its default UI.

For web integrations:

* Set [`headless: true`](/messaging/web/sdk-api-reference#headless) to hide the default button and drawer.
* Set [`enableProgrammaticControl: true`](/messaging/web/sdk-api-reference#enableprogrammaticcontrol) to allow `getConversation`, `getMessages`, [`selectQuickReply`](/messaging/web/sdk-api-reference#selectquickreply), `sendMessage`, and the `ada:message:sent` and `ada:message:received` events.

`selectQuickReply` selects a stored quick reply by message ID and index.
It is available on Web, [iOS](/messaging/ios/sdk-api-reference#selectquickreply), [Android](/messaging/android/sdk-api-reference#selectquickreply), and [React Native](/messaging/react-native/sdk-api-reference#selectquickreply).

Use it when:

* Your web page renders a search bar, sidebar, command palette, or inline helper.
* Your page sends messages for the end user, such as a recording link.
* Your mobile app builds UI from message events, such as an unread badge. See the [mobile SDKs](/messaging/introduction/overview#supported-platforms).

> **Warning**
>
> Every script on your host page can subscribe to these events or call these methods.
> Scripts receive full message bodies, including personal information that end users type.
> Have your product and security teams accept that exposure before you enable programmatic control.

Review [Limit transcript exposure](/messaging/web/security-best-practices#limit-transcript-exposure) before you enable programmatic control.
Compare UI deployment and SDK capabilities with [custom apps](#custom-apps) below.

## Custom apps

Use a custom app for a conversation UI that you host and share across web and mobile. Ada handles the session, transport, and security.

Set `appUrl` to your hosted `https:` URL. Connect your app through `@ada-cx/messaging-bridge`.

| Comparison                                       | Custom app                                                                                                                                                    | Headless                                                                                                                                                                                                                               |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Where your UI lives                              | One hosted web app, loaded in Ada's frame or mobile WebView.                                                                                                  | Your website or native app code.                                                                                                                                                                                                       |
| How you ship a UI change                         | Deploy the hosted web app once.                                                                                                                               | Deploy each website. Release each native app through its app store. End users must install the update.                                                                                                                                 |
| What reaches mobile without an app store release | Your updated UI on the next Ada view load, subject to HTTP caching.                                                                                           | No changes to your native UI.                                                                                                                                                                                                          |
| SDK capabilities                                 | Full [display state](/messaging/custom-apps/state-and-events) and the [typed operations](/messaging/custom-apps/operations) that Ada's conversation app uses. | Events, `getConversation`, `getMessages`, [`selectQuickReply`](/messaging/web/sdk-api-reference#selectquickreply), and `sendMessage` on every platform. Turn on `enableProgrammaticControl` first. React Native enables it by default. |

See [Deploy once, update everywhere](/messaging/custom-apps/overview#deploy-once-update-everywhere) for the one-time setup, **Allowed websites** requirement, and caching guidance.

## Mobile SDKs

The mobile SDKs embed the AI Agent inside iOS, Android, and React Native applications. They support identity tokens, headless mode, programmatic `selectQuickReply` and `sendMessage`, and event subscriptions.

Use them when:

* The AI Agent is delivered through a mobile application.

See the [iOS](/messaging/ios/overview), [Android](/messaging/android/overview), and [React Native](/messaging/react-native/overview) overviews.

## Conversations API

The Conversations API is a server-to-server integration. A server authenticates with Ada over HTTP and exchanges messages with the AI Agent. Custom Channels are built on this API.

Use it when:

* The integration runs on a server, for example syncing with a CRM.
* Messages are delivered on a channel Ada does not render, such as SMS or a proprietary application.
* Messages are sent without an active browser session, such as scheduled outbound messages.

See the [Conversations API overview](/reference/conversations/overview).

## Messaging SDK or Conversations API?

Both let an integration read and send messages, so the deciding factor is where the integration runs.

* Choose the **Messaging SDK** when the integration runs in the end user's browser or mobile app. It reuses the existing session, handoffs, and live-agent state, and requires no server.
* Choose the **Conversations API** when the integration runs on a server, on a channel Ada does not render, or without an active session.

Most requests to customize chat or to automate the conversation from the client fit the Messaging SDK. Reach for the Conversations API when the integration genuinely lives on a server.