Incorpore a Caixa de Entrada do Chat

​

Pré-requisitos compartilhados (Chat + Connect)

1. Chave de API do tenant (ps_, com escopo de tenant) — gerada em Perfil → API. Ela nunca sai do seu backend. (Uma chave com escopo de número só pode incorporar o próprio número.)
2. SDK — <script src="https://pilotstatus.com.br/embed.js"> ou npm i @pilot-status/embed; chame PilotStatus.init().
3. allowedOrigins — ao emitir o token do Chat, liste as origens exatas (scheme://host[:port], 1–20) autorizadas a incorporar.
4. Token por superfície — o Chat usa POST /v1/embed/sessions (surface: "chat", um JWT de curta duração mantido em memória). O Connect usa POST /v1/numbers/remote-pairing (um token de pareamento na URL — veja Incorpore a Página de Connect).
5. Renovação — o TTL do token do Chat é de 15 min com uma janela de atualização deslizante; ao expirar por completo, o SDK chama onSessionExpired.

​

Fluxo do Chat

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>

​

Protocolo postMessage (pai ↔ iframe)

​

Modelo de segurança

• A x-api-key fica apenas no seu backend; o navegador só manipula o JWT de curta duração.
• O JWT tem escopo rígido para os seus whatsappNumberIds — as rotas do chat reverificam a cada requisição (defesa em profundidade).
• Token apenas em memória, TTL de ~15 min com atualização deslizante; allowedOrigins fixa quem pode incorporar; a origem do postMessage é validada em ambos os lados.

​

Relacionados

• Incorpore a Página de Connect
• Painel de Chat ao Vivo