Getting started

This guide builds a custom conversation app, connects it to the Messaging runtime with @ada-cx/messaging-bridge, and points the Web SDK at it. Read the custom apps overview first for the architecture and requirements.

Before you start

• You need your AI Agent’s handle.
• Add your app’s origin to your handle’s Allowed websites list. In your Ada dashboard, go to Channels > Chat. Custom apps stay disabled while the list has no entry that allows your origin. An empty list disables custom apps for the handle.
• The same list controls which websites can embed the chat widget. When the list has entries, keep every website that embeds the widget in it too. Hosting your app on a website that the list already allows needs no new entry.
• Host your app on an absolute https: URL, on an origin you control. For local development, an http: URL on a loopback host such as http://localhost:5173 is also accepted. Other http: URLs, relative URLs, and data: URLs are rejected, and so are Ada-hosted origins.

Local development

Two development setups exist, and only one needs configuration:

• Pure local (zero configuration). A loopback appUrl, such as http://localhost:5173, is allowed implicitly when the page that embeds the widget also runs on a loopback host (localhost, 127.0.0.1, [::1], or a *.localhost subdomain). No Allowed websites entry is needed. In Chrome and Firefox, you must grant one browser permission. See below.
• Hybrid (deployed page, local app). A deployed page gets no implicit loopback allowance. Expose your development server through an https: tunnel, and add the tunnel origin to Allowed websites. The dashboard accepts only https:// entries. This setup needs no browser permission, and it works in every browser.

Grant the local network permission

Chrome 142 and later gate requests from public sites to loopback and local addresses behind a Local Network Access permission. Ada’s core frame loads from a public Ada origin. Its navigation to your loopback appUrl is such a request. Ada’s frames delegate the permission down the frame chain automatically when your appUrl is a loopback URL. Ada never delegates it for other appUrl values.

With the delegation in place, Chrome shows a permission prompt for your page. The prompt names your local page and asks to look for and connect to devices on your local network. Click Allow. Chrome remembers your choice for the site. You can change it later in Site settings, under the local network permissions.

Set appUrl in the settings that the page starts with. The browser fixes the delegation when the widget frames mount. An appUrl that arrives later cannot enable it.

If the permission is missing or denied, the browser blocks the navigation before your app loads. The widget then falls back to the default app with handshake_timeout. DevTools shows the blocked request as ERR_BLOCKED_BY_LOCAL_NETWORK_ACCESS_CHECKS.

Browser support differs:

• Chrome and Edge (Chromium 142 and later): prompt appears, click Allow once.
• Firefox (rolling out from version 149): a similar prompt appears.
• Safari: no Local Network Access gate today. The loopback path works without a prompt.

Ada delegates the loopback half of the permission only. An RFC 1918 address such as 192.168.1.10 is not a loopback host. Neither the http: nor https: form gets the delegation.

If you cannot grant the permission, use the hybrid https: tunnel setup instead. It avoids the permission entirely.

Step 1: Install the bridge package

1
npm install @ada-cx/messaging-bridge

The package carries TypeScript types, test mocks, and a thin loader. The bridge runtime always loads from Ada’s CDN, so the npm version never pins the runtime.

Step 2: Allow Ada to frame your app

Ada’s core frame mounts your app inside an iframe. The core frame is served from Ada’s asset host, and it sits inside your own page. Browsers check framing restrictions against every ancestor frame, so your app’s ancestor chain contains both origins: Ada’s asset host and the site that embeds the widget.

If your app’s responses send no X-Frame-Options header and no frame-ancestors directive, browsers permit framing. No server change is needed.

If your app restricts framing, its frame-ancestors directive must allow Ada’s asset hosts and every site origin that embeds the widget:

Content-Security-Policy: frame-ancestors https://messaging-assets.ada.support https://static.ada.support https://your-site.com

• Replace https://your-site.com with every origin where your pages embed the Ada widget.
• Add the directive to your existing policy. Do not replace your other directives.
• Remove any X-Frame-Options header from the app’s response. frame-ancestors replaces it.
• For staging validation, also allow the Ada-provided asset host and your staging site origins.

A blocked frame shows nothing inside the frame. The app.initialize handshake never arrives, the 15-second timeout fires, and Messaging falls back to the default app with a console warning. Always test your policy inside the real embed on a page that sets appUrl. Opening your app URL directly in a browser tab does not exercise frame-ancestors.

Step 3: Connect to the bridge

Load the runtime, create a client, and complete the handshake. This path works with any framework, or none.

1
import { loadMessagingBridge } from "@ada-cx/messaging-bridge";
2
3
const bridge = await loadMessagingBridge();
4
const client = bridge.createBridgeClient();
5
6
// REQUIRED: send app.initialize within 15 seconds of your frame loading.
7
// If the handshake does not arrive, core unmounts your frame.
8
client.sendEvent("app.initialize");
9
10
// Re-render when the transcript changes, and report what the end
11
// user has read. Only durable rows carry a cursor, so drive markRead
12
// from this subscription. markRead is debounced and monotonic.
13
const unsubscribe = client.subscribeKey("chat.messages", (messages) => {
14
  renderMessages(messages ?? []);
15
  for (const message of messages ?? []) {
16
    if (message.cursor) client.operations.markRead(message.cursor);
17
  }
18
});
19
20
// Send a user message. The handle resolves with the message row.
21
// It settles with the optimistic row, which has no cursor yet; the
22
// cursor arrives on the durable echo, which the subscription above
23
// sees. Never drive markRead from the settled row.
24
const handle = client.operations.sendMessage("Hello");
25
await handle.settled();
26
27
// Tear down when your app unmounts.
28
unsubscribe();
29
client.destroy();

client.operations wraps every supported event with the guards and correlation logic that Ada’s own conversation app uses. client.subscribeKey(key, callback) fires only when one key’s value changes. See the Operations reference for the full surface, and State and events for when each state key updates.

loadMessagingBridge() memoizes the load, so repeated calls return the same promise. A failed load is forgotten, and a later call retries. The promise rejects with a MessagingBridgeLoadError. The error’s code property identifies the failure:

Read state with plain keys, or use the STATE constants from the loaded module for typo-safe access:

1
const agentName = client.getState()?.[bridge.STATE.CONFIG_BOT_NAME];

Render conversation content safely

Treat every string in the display state as untrusted data. message.body is a plain string. It can contain end-user input, AI Agent output, and content from knowledge sources.

• Render bodies as text. In React, JSX text rendering (<p>{message.body}</p>) escapes them for you. In plain DOM code, use textContent.
• Never assign a body to innerHTML, and never pass one to dangerouslySetInnerHTML.
• If you convert bodies from Markdown to HTML, sanitize the HTML output before you insert it into the document.

Your app frame holds the whole transcript. A single injected script in that frame can read every message.

React

The ./react entry provides a provider and hooks. createBridgeProvider handles loading, the app.initialize handshake, and teardown for you:

1
import { createBridgeProvider, useBridgeState } from "@ada-cx/messaging-bridge/react";
2
3
const AdaBridgeProvider = createBridgeProvider();
4
5
function Root() {
6
  return (
7
    <AdaBridgeProvider fallback={<Spinner />}>
8
      <MyChatUi />
9
    </AdaBridgeProvider>
10
  );
11
}
12
13
function MyChatUi() {
14
  const state = useBridgeState();
15
  return <MessageList messages={state?.["chat.messages"] ?? []} />;
16
}

If your app lazily loads the route that renders AdaBridgeProvider, add a bare import "@ada-cx/messaging-bridge"; to your entry module. The loader then snapshots the frame name at startup, before other code can overwrite window.name.

To own the lifecycle yourself, create a client and pass it to BridgeProvider. With an injected client, you send app.initialize and call destroy() yourself:

1
import { BridgeProvider } from "@ada-cx/messaging-bridge/react";
2
3
<BridgeProvider client={client}>
4
  <MyChatUi />
5
</BridgeProvider>

The hooks are useBridgeClient(), useBridgeState(), and useBridgeStateKey(key). useBridgeStateKey re-renders only when its key’s value changes; useBridgeState re-renders on every state update. Reach the operations layer through useBridgeClient().operations.

Step 4: Point the Web SDK at your app

Set appUrl in the configuration you pass to the Web SDK on your host page:

1
import { loadAdaMessaging } from "@ada-cx/messaging-sdk";
2
3
const ada = await loadAdaMessaging({
4
  handle: "<your-handle>",
5
  appUrl: "https://app.example.com/ada-chat/",
6
});

The same settings work with adaEmbed.start() on the module-script path.

Rules the runtime enforces:

• appUrl must be an absolute https: URL without embedded credentials, on an origin you control. For local development, http: is accepted on loopback hosts such as localhost and 127.0.0.1. The SDK drops any other value with a console warning, and the default app mounts. Ada-hosted origins and the Messaging frame’s own origin are also rejected.
• The URL’s origin must be allowed by your handle’s Allowed websites list. Add it in your Ada dashboard, under Channels > Chat. An entry that carries a path, query, or fragment does not authorize a custom app. Add the bare origin as its own entry. Exception: a loopback origin is allowed implicitly when the embedding page itself runs on a loopback host. See Local development. A URL that the list does not allow follows the fallback rules below, with the code origin_not_allowlisted.
• The value locks on first configuration. A later configuration change or reset() cannot redirect the app frame to a different URL.
• Ada appends no query parameters to your URL. Your app receives all state through the bridge.
• Your app must not navigate or reload its own frame. The bridge is pinned to the first document, and a navigation disconnects it permanently. This applies even when the navigation stays on the same origin. To show other pages inside your app, mount your own inner iframe instead.

Step 5: Choose your fallback posture

By default, Ada replaces a failed custom frame with the default app. This happens when the frame fails to load, fails its handshake, or fails the Allowed websites check. It also happens when your handle’s configuration does not load in time to verify the Allowed websites list. Set appUrlFallback: false to fail closed instead:

1
await loadAdaMessaging({
2
  handle: "<your-handle>",
3
  appUrl: "https://app.example.com/ada-chat/",
4
  appUrlFallback: false,
5
});

With fallback disabled, the failure follows the normal activation error path, and later activation attempts retry your URL. In this mode, the ada.customApp.fallback event does not fire. appUrlFallback is only meaningful together with appUrl, and it also locks on first configuration.

Step 6: Watch for fallbacks

Subscribe to the ada.customApp.fallback diagnostic event on your host page. It fires when a custom frame is abandoned, with the attempted URL and the cause:

1
await ada.subscribeEvent("ada.customApp.fallback", (data) => {
2
  // data: { appUrl: string, reason: string, code: string, retryable: boolean }
3
  reportToYourTelemetry("ada-custom-app-fallback", data);
4
});

Branch on code, the stable machine-readable cause. The reason string is human-readable and can change between releases. code has one of these values:

A handshake_timeout does not prove that your app code ran. Browsers count an HTTP error page as a produced document. They also count a page they blocked with X-Frame-Options or frame-ancestors, and a Local Network Access error page for a blocked loopback appUrl (see Grant the local network permission). Check the URL, your framing headers, and the browser permission first, then your bridge client.

When retryable is false, the fallback is permanent for the page. The default app serves until the page reloads with the cause fixed. When retryable is true, the next mount after a reset() verifies your URL against the loaded Allowed websites list again.

Wire this into your monitoring before launch. A fallback is invisible to end users when appUrlFallback is on, so this event is your only signal. The event fires only when a fallback runs. With appUrlFallback: false, it never fires, and failures surface through the activation error path.

Step 7: Test your app

The ./testing entry provides a scriptable in-memory client. It performs no postMessage and no network access:

1
import { createMockBridgeClient } from "@ada-cx/messaging-bridge/testing";
2
3
const mock = createMockBridgeClient();
4
render(<BridgeProvider client={mock}><MyChatUi /></BridgeProvider>);
5
6
mock.updateState({ "chat.isSending": true });
7
expect(mock.sentEvents).toContainEqual({
8
  event: "chat.message.send",
9
  payload: expect.objectContaining({ body: "Hello" }),
10
});

Mock helpers: clearSentEvents, destroyed, sentEvents, setState, subscriberCount, and updateState.

The mock implements the full client surface, operations included. Every operation records its events in sentEvents, and a correlated handle resolves when your test scripts the answering state change:

1
const handle = mock.operations.sendMessage("Hello");
2
mock.updateState({
3
  "chat.messages": [
4
    { type: "text", id: "m1", sender: "user", timestamp: 1,
5
      body: "Hello", clientKey: handle.tempMessageUuid },
6
  ],
7
});
8
await handle.settled();

Staging validation

To validate against a different asset host, pass its root to the bridge loader. Ada gives you the host value when you arrange a preproduction validation:

1
const bridge = await loadMessagingBridge({
2
  cdnBase: "<ada-provided-asset-host>",
3
});

Use cdnBase for staging validation only. Production pages must keep the default.

Preview and pre-release builds are Ada-internal workflows. When your Ada team runs a joint validation with a preview build, the preview core automatically selects its matching bridge. You do not need a cdnBase override for that: when the page loads sdk.js from the production asset root, the pairing is automatic.

Match the core build

Ada core stamps its build identifier into your frame’s window.name as ada-custom-app:<build identifier> before your app code runs. Your URL and its fragment mount untouched, so hash routes keep working.

The loader accepts only these marker shapes. It never accepts a URL or path from the frame name.

The loader snapshots window.name when your app first evaluates the package, through either entry: @ada-cx/messaging-bridge or @ada-cx/messaging-bridge/react. Keep that import in a module your page evaluates at startup. A route-level code split evaluates too late. Code that runs first, for example a library that uses window.name, could overwrite the name. The loader keeps the snapshot value if code overwrites window.name later.

Do not persist or replay the frame-name marker. Core supplies the authoritative value for every frame load.

Do not set or change window.name. The loader fails closed when your page runs outside an Ada-mounted custom app frame.

Local core builds use the dev marker. This marker works only with a loopback cdnBase.