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

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 or the npm loader package instead; both render the same launcher and drawer. See Security best practices for the reasoning.

See Migrate from the Chat SDK web script.

Module-script import

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

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

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.

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

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. See 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 to hide the default button and drawer.
• Set enableProgrammaticControl: true to allow getConversation, getMessages, 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, Android, and React Native.

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.

Review Limit transcript exposure before you enable programmatic control. Compare UI deployment and SDK capabilities with 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.

See 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, Android, and React Native 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.

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.