Embed navigation

The widget runs in a sandboxed iframe and cannot change your site’s URL directly. When a customer taps a Navigation card, the iframe sends a postMessage to the host page. You must register a listener on the host page to handle that intent. Navigation deeplinks only work when both parts are on your page:

The iframe: loads the chat UI from Chatropic.
A host script: defines setupChatropicNavigationListener and wires it to your router or location.assign.

The Embed tab on Deploy > Chat widget currently copies the iframe setup only. If you are using Navigation cards, add the listener below manually in your host app.

Full embed example

Use the iframe src from the Embed tab on Deploy > Chat widget. Current web snippets use https://chatropic.com/embed/key/{publishable-key}.

<!-- 1. Chatropic inline panel iframe -->
<iframe
  id="chatropic"
  src="https://chatropic.com/embed/key/cpk_live_..."
  width="400"
  height="620"
  style="border:none;border-radius:16px;box-shadow:0 8px 30px rgba(0,0,0,0.12)"
  allow="microphone"
  title="Support assistant"
></iframe>

<!-- 2. Host listener, required for Navigation card deeplinks -->
<script>
/**
 * Handle Navigation card deeplinks from the Chatropic embed iframe.
 * @param {string} widgetOrigin - Origin of your embed URL (scheme + host + port)
 * @param {(path: string) => void} [onNavigate] - Optional handler (e.g. router.push)
 */
function setupChatropicNavigationListener(widgetOrigin, onNavigate) {
  var ALLOW = /^\/[a-zA-Z0-9\-\/_?=&]*$/;
  window.addEventListener("message", function (e) {
    if (e.origin !== widgetOrigin) return;
    var d = e.data || {};
    if (d.type !== "chatropic:navigate") return;
    if (typeof d.path !== "string" || !ALLOW.test(d.path)) return;
    if (typeof onNavigate === "function") {
      onNavigate(d.path);
      return;
    }
    window.location.assign(d.path);
  });
}

// Default: full page navigation
setupChatropicNavigationListener("https://chatropic.com", function (path) {
  // SPA hosts: replace with router.push(path) or navigate(path)
  window.location.assign(path);
});
</script>

If you paste only the iframe without the listener script, Navigation cards will appear in chat but clicks will not navigate your site. This applies to both the website widget and inline panel snippets.

The snippet from Copy website widget code on the Embed tab includes setupChatropicLauncherHostListener and embed wake scripts. The iframe src includes mode=launcher. When integrating manually, register one navigation listener per page. A single listener handles navigation messages from either embed layout.

`setupChatropicLauncherHostListener`

The website widget posts chatropic:launcher-state messages when chat opens or closes on mobile. The host listener resizes the iframe between a compact closed footprint and full viewport when open.

Argument	Type	Description
`widgetOrigin`	`string`	Origin of your embed URL (scheme and host, no path)
`iframeId`	`string` (optional)	Host iframe element id, default `chatropic-launcher`

Paste this from the copied website widget snippet rather than hand-rolling iframe sizing on mobile.

If you paste only the launcher iframe without the host scripts, Navigation cards will not navigate your site and mobile chat may not expand correctly.

`setupChatropicNavigationListener`

This is the function integrators install on the host page (the page that contains the iframe, not inside the iframe).

Argument	Type	Description
`widgetOrigin`	`string`	Origin of your embed URL (scheme and host, no path)
`onNavigate`	`(path: string) => void` (optional)	Called with a validated relative path when the user clicks a Navigation card

What it does

Subscribes to window.message on the host page.
Accepts messages only when event.origin === widgetOrigin.
Handles messages where event.data.type === "chatropic:navigate".
Validates event.data.path is a relative URL (starts with /, no javascript: or https://).
Calls your onNavigate(path) callback, or falls back to window.location.assign(path).

Message protocol

When the user clicks a Navigation card inside the iframe, the widget posts to window.parent:

{
  "type": "chatropic:navigate",
  "path": "/account/billing"
}

Only relative paths from your tenant’s navigation route registry are ever sent.

SPA integration

Pass a custom onNavigate callback instead of relying on location.assign:

// Next.js App Router, host layout or page that renders the iframe
import { useRouter } from "next/navigation";

const router = useRouter();

setupChatropicNavigationListener("https://chatropic.com", function (path) {
  router.push(path);
});

// React Router v6
import { useNavigate } from "react-router-dom";

const navigate = useNavigate();

setupChatropicNavigationListener("https://chatropic.com", function (path) {
  navigate(path);
});

// Vue Router
setupChatropicNavigationListener("https://chatropic.com", function (path) {
  router.push(path);
});

Reuse the listener on multiple pages

Define the function once in a shared bundle or layout, then call setupChatropicNavigationListener on every page that embeds the iframe:

// shared/chatropic-embed.js
export function initChatropicEmbedNavigation(widgetOrigin, navigate) {
  setupChatropicNavigationListener(widgetOrigin, navigate);
}

Security

Check	Purpose
`e.origin === widgetOrigin`	Ignore messages from other sites
Path allowlist regex	Reject `https://...`, `javascript:...`, and other non-relative paths
Server-side route registry	The agent only offers paths stored in your tenant’s `nav_routes`: never user-supplied URLs

UI payload shape

Sync responses and agent:done events may include:

{
  "component": "NavigationCard",
  "props": {
    "label": "Billing",
    "path": "/account/billing",
    "requiresAuth": true
  }
}

The default web embed renders this automatically. On mobile, the React Native SDK delivers the same payload through onNavigate; see React Native SDKOn mobile, the React Native SDK delivers the same payload through onNavigate; see React Native SDK.

Click analytics (optional)

The widget dispatches chatropic:nav-card-clicked on the iframe window when the user taps the card. Listen from host instrumentation if needed:

// Optional, only if you inject listeners into the iframe context
window.addEventListener("chatropic:nav-card-clicked", function (e) {
  console.log("Nav card clicked", e.detail); // { path, label }
});

Web embed

Copy website widget or inline panel snippets from Deploy, Chat widget.

Navigation routes

Configure destinations for the agent.

Quick Start

Integration

Navigation Routes

Reference

Embed the widget (iframe + optional listener)

Full embed example

Website widget (floating launcher)

`setupChatropicLauncherHostListener`

`setupChatropicNavigationListener`

What it does

Message protocol

SPA integration

Reuse the listener on multiple pages

Security

UI payload shape

Click analytics (optional)

Web embed

Navigation routes

​Embed the widget (iframe + optional listener)

​Full embed example

​Website widget (floating launcher)

​setupChatropicLauncherHostListener

​setupChatropicNavigationListener

​What it does

​Message protocol

​SPA integration

​Reuse the listener on multiple pages

​Security

​UI payload shape

​Click analytics (optional)

Web embed

Navigation routes

Embed the widget (iframe + optional listener)

Full embed example

Website widget (floating launcher)

`setupChatropicLauncherHostListener`

`setupChatropicNavigationListener`

What it does

Message protocol

SPA integration

Reuse the listener on multiple pages

Security

UI payload shape

Click analytics (optional)