The message bridge

One contract, two transports. The action names and payloads are identical in both — only the envelope and the delivery mechanism change.

Transport A: native WebView

This is the transport the iOS and Android SDKs use, and the one to pick whenever you control a native WebView.

Web → host. The runtime looks for one object and calls postMessage on it:

The name is exact and case-sensitive: loopsAIBridge.

Host → web. Evaluate one line of JavaScript in the page:

window.postMessage(<envelope JSON>, "*");

Transport B: web iframe

Use this when the chat lives in an <iframe> inside a page your app already renders (Capacitor, Cordova, Ionic, an in-app HTML screen).

• Web → host: the runtime posts to window.parent with targetOrigin: "*". Always check event.origin === "https://chat.loopsai.com" before you trust a message.
• Host → web: iframe.contentWindow.postMessage(envelope, "https://chat.loopsai.com").
• You must pass parentOrigin (URL-encoded) on the iframe src. The runtime only accepts inbound messages from its own origin, the referrer origin, and parentOrigin. Miss it and every command you send is dropped in silence.
• Add allow="camera; microphone" to the <iframe> or try-on and voice mode cannot reach the hardware.

The envelope

What you send — use the typed envelope on both transports; the runtime accepts it either way:

{
  "protocolVersion": 1,
  "type": "nativeAction",
  "name": "updateContext",
  "requestId": "req_1",          // optional, for your own correlation
  "payload": { "productContext": { "productCode": "SKU123" } }
}

What you receive depends on the transport:

{
  "protocolVersion": 1,
  "type": "nativeAction",
  "name": "openExternalUrl",
  "requestId": "req_1753…_4",
  "payload": { "url": "https://shop.example.com/p/123?utm_source=loopsai", "target": "_blank" }
}

{ "action": "openExternalUrl", "url": "https://shop.example.com/p/123", "target": "_blank" }

Rules that hold in both directions:

• Unknown action names are ignored, never an error. You can send an action a future runtime understands, and receive one your app has never heard of — check the name and drop what you don't handle.
• protocolVersion is 1. It exists so a shipped app keeps working when the protocol grows.
• Everything is fire-and-forget. There are no responses, no acknowledgements, and no error messages in either direction.

The handshake

ready fires once the runtime has attached its message listener. Anything you send before it is lost — the listener does not exist yet, and there is no queue on the web side. Send initConfig / initContext from your ready handler, and guard later calls with a simple isReady flag (queue them yourself if a user can tap a button during load).

Web → host actions

Everything the runtime tells you. Only the first two require action on your side.

Host → web actions

Web-embed-only actions (setEmbedFooterHeight, forwardHeaderTap, viewportGeometry, trackAnalytics) belong to the website bubble / bottom-bar shell. Ignore them in a mobile container.

initConfig

Theme, copy, and which flows exist all come from your agent's published configuration, so this message is for the handful of things only the container knows:

{
  "protocolVersion": 1,
  "type": "nativeAction",
  "name": "initConfig",
  "payload": {
    "config": {
      "closeButtonEnabled": true,
      "theme": "dark",
      "chatHistoryEnabled": false
    }
  }
}

Copy overrides are also accepted (displayName, welcomeTitle, welcomeDescription, initialMessage, messagePlaceholder, privacyText, privacyPolicyUrl). Prefer the dashboard for these so web and mobile stay in sync.

Analytics

In mode=sdk the runtime stops sending canonical events to its own analytics sink and hands each one to you instead:

{ "name": "trackEvent",
  "payload": { "event": { "event": "loops_ai_select_item", "channel": "ios", "…": "…" } } }

Forward payload.event to your provider (Firebase Analytics, GA4, Segment, a webhook — anything that accepts a flat JSON event). kind: "interaction" marks a customer-facing interaction event rather than a canonical ecommerce one.

Event names and fields: Canonical events.

Security

What the runtime enforces, and what you must enforce.

The runtime:

• Accepts inbound messages only from its own origin, the referrer origin, and parentOrigin. A native window.postMessage is same-origin, so it always passes; an iframe host must pass parentOrigin.
• Ignores unknown action names.

You:

• Verify the sender. iOS: check message.frameInfo.isMainFrame and that the frame's host is chat.loopsai.com. Iframe: check event.origin. Android: prefer WebViewCompat.addWebMessageListener with an origin rule when the device supports it, otherwise pin navigation to the chat host (below).
• Keep the WebView on one host. addJavascriptInterface exposes your bridge to every page the WebView loads, so intercept navigation (shouldOverrideUrlLoading, decidePolicyFor) and route anything that is not chat.loopsai.com out of the WebView.
• Send the exact origin when posting into an iframe — never "*".
• Keep secrets out of context. productContext and userContext are forwarded to the assistant and may appear in conversation logs and analytics. Send an opaque customer id, not tokens or full personal records.

Next: Flow modes.