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:

1
<script type="module">
2
  import { createAdaEmbedInterface } from "https://messaging-assets.ada.support/sdk.js";
3
4
  const adaEmbed = createAdaEmbedInterface();
5
  await adaEmbed.start({ handle: "<your-handle>" });
6
</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

The SDK can connect to the AI Agent without rendering the built-in button or drawer. Set headless: true to suppress the default UI, and set enableProgrammaticControl: true to unlock the transcript-bearing surface: sendMessage, getMessages, getConversation, and the ada:message:sent / ada:message:received events.

Use it when:

• A web page renders its own chat surface, such as a search bar, sidebar, slash-command palette, or inline helper.
• An in-page tool sends messages on behalf of the end user, for example passing a recording link into the conversation.
• A mobile app drives its own UI, such as an unread-message indicator built from message events, using the mobile SDKs’ headless mode.

See the headless and enableProgrammaticControl settings in the SDK API reference, and Limit transcript exposure in the security best practices.

Custom app frames

Custom app frames replace the built-in conversation UI with an app you host, while Ada keeps running the session, transport, and security layers. You provide an https: URL through the appUrl setting, and your app talks to the SDK through @ada-cx/messaging-bridge.

Use it when:

• You need a fully custom conversation UI beyond what settings and styles allow.
• Your handle’s Allowed websites list allows your app’s origin.

See Custom apps.

Mobile SDKs

The mobile SDKs embed the AI Agent inside iOS, Android, and React Native applications. They support identity tokens, headless mode, programmatic 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.