Embed the Chat Inbox

​

Shared prerequisites (Chat + Connect)

1. Tenant API key (ps_, tenant-scoped) — generated in Profile → API. It never leaves your backend. (A number-scoped key can only embed its own number.)
2. SDK — <script src="https://pilotstatus.com.br/embed.js"> or npm i @pilot-status/embed; call PilotStatus.init().
3. allowedOrigins — when minting the Chat token, list the exact origins (scheme://host[:port], 1–20) allowed to embed.
4. Token per surface — Chat uses POST /v1/embed/sessions (surface: "chat", a short-lived JWT kept in memory). Connect uses POST /v1/numbers/remote-pairing (a pairing token in the URL — see Embed the Connect Page).
5. Renewal — Chat token TTL is 15 min with a sliding refresh window; on full expiry the SDK calls onSessionExpired.

​

Chat flow

curl -X POST "https://pilotstatus.com.br/v1/embed/sessions" \
  -H "x-api-key: ps_your_tenant_key" \
  -H "Content-Type: application/json" \
  -d '{
    "surface": "chat",
    "whatsappNumberIds": ["wn_abc123"],
    "allowedOrigins": ["https://app.yoursaas.com"],
    "ttlSeconds": 900
  }'

<script src="https://pilotstatus.com.br/embed.js"></script>
<div id="inbox"></div>
<script>
  PilotStatus.init();
  const { token } = await fetch("/api/my-saas/embed-token").then(r => r.json());
  const chat = PilotStatus.chat.mount("#inbox", {
    token, locale: "en", theme: "light",
    onUnreadCount: (n) => {},
    onConversationOpened: (id) => {},
    onSessionExpired: async () => {
      const { token: t } = await fetch("/api/my-saas/embed-token").then(r => r.json());
      chat.destroy();
      PilotStatus.chat.mount("#inbox", { token: t, locale: "en" });
    },
  });
  // chat.setTheme("dark"); chat.setLocale("pt"); chat.destroy();
</script>

​

postMessage protocol (parent ↔ iframe)

​

Security model

• x-api-key lives only on your backend; the browser only ever handles the short-lived JWT.
• The JWT is hard-scoped to its whatsappNumberIds — the chat routes re-check on every request (defense in depth).
• Token in memory only, ~15 min TTL with sliding refresh; allowedOrigins pins who may embed; postMessage origin is validated on both sides.

​

Related

• Embed the Connect Page
• Live Chat dashboard