Skip to main content

​
Incorporando microfrontends — tokens de embed

O Pilot Status permite que um tenant incorpore dois microfrontends no seu próprio SaaS, em white-label, por meio de um iframe hospedado + um pequeno JS SDK. Seus clientes permanecem dentro do seu produto e veem a sua marca.

​
As duas superfícies

O documento do iframe é hospedado em um subdomínio do Pilot, então suas próprias chamadas /api são same-origin — não há CORS para você configurar. As únicas chamadas que você faz são servidor-a-servidor para gerar tokens.

​
POST /v1/embed/sessions — Gerar um token de embed do Chat

Gere tokens de embed no seu backend, nunca no navegador. Autenticado com a chave de API ps_ do seu tenant (header x-api-key).
​
string
obrigatório
"chat" ou "connect" — para qual microfrontend o token é.
​
string[]
Obrigatório para surface: "chat" — os números sobre os quais o embed pode atuar. Uma chave ps_ com escopo de número ignora isso e é forçada ao seu próprio número.
​
string[]
obrigatório
Origens exatas autorizadas a enquadrar o embed (mín. 1), ex. ["https://app.tenant.com"].
​
object
Override opcional de branding por sessão (veja White-label abaixo).
​
number
Tempo de vida do token. Padrões: chat 15 min, connect 30 min.
Resposta 201:
O token é de curta duração. O SDK o injeta no iframe em memória — nunca em uma URL.

​
POST /api/public/embed/refresh — Renovação deslizante

O iframe apresenta seu token de embed atual (ainda válido) como Authorization: Bearer <token> e recebe um novo (renovação deslizante). Na expiração total, o SDK chama onSessionExpired para que você possa gerar um novo via seu backend.
Connect usa um token diferente. Para a superfície Connect, o iframe é autorizado pelo token de pareamento remoto existente (aquele retornado por POST /v1/numbers/remote-pairing como remotePairingUrl — veja Pareamento Remoto). O token de POST /v1/embed/sessions é para o Chat.

​
JS SDK — @pilot-status/embed

Disponível como pacote npm e como script CDN.
  • PilotStatus.chat.mount(selector, options) — monta o iframe da caixa de entrada do WhatsApp (padrão https://chat.pilotstatus.com.br). Passe o token de embed do chat, além de locale, theme opcionais e callbacks (onUnreadCount, onConversationOpened, onSessionExpired).
  • PilotStatus.connect.open(options) — abre o fluxo de connect (pareamento remoto) (padrão https://connect.pilotstatus.com.br). Passe o token de pareamento remoto, além dos callbacks onPaired, onError, onExpired.
Ou instale do npm em vez do script CDN:

​
Segurança

  • Gere tokens no servidor. Nunca exponha sua chave ps_ no navegador — apenas seu backend chama POST /v1/embed/sessions (e POST /v1/numbers/remote-pairing).
  • Tokens são de curta duração (chat 15 min / connect 30 min por padrão) e renovam em uma janela deslizante.
  • allowedOrigins vincula quais sites podem enquadrar o embed (origens exatas, mín. 1).
  • Um token de embed tem escopo rígido para seus whatsappNumberIds — ele só pode atuar sobre esses números.

​
White-label

O embed reutiliza o branding existente do tenant configurado na aba Branding/Marca do dashboard — logo, cores primária/de fundo, nome da empresa e o toggle “ocultar Pilot Status” (veja Branding da página Connect). Você pode adicionalmente passar um objeto brandingOverride opcional em POST /v1/embed/sessions para sobrescrever o branding apenas para aquela sessão.