Adicione a este projeto um endpoint de backend que gera uma sessão de cadastro
de WhatsApp na API da Pilot Status.

Crie uma rota do lado do servidor: POST /api/pilot/pairing-session

Ela recebe um corpo JSON: { "customerId": string, "customerName": string }
onde customerId é o id do cliente logado no banco de dados deste app.

A rota precisa chamar a API da Pilot Status pelo servidor:

  POST https://pilotstatus.com.br/v1/numbers/remote-pairing
  Headers:
    Content-Type: application/json
    x-api-key: <o valor da variável de ambiente PILOT_TENANT_KEY>
  Body:
    {
      "provider": "META",
      "metaFlow": "embedded",
      "name": "<customerName>",
      "externalRef": "<customerId>"
    }

A resposta de sucesso é HTTP 201, exatamente com este formato:

  {
    "provider": "META",
    "remotePairingUrl": "https://connect.pilotstatus.com.br/connect/<token>",
    "expiresAt": "2026-07-20T18:30:00.000Z"
  }

O token de cadastro é o ÚLTIMO SEGMENTO DO PATH de remotePairingUrl. Extraia
com new URL(remotePairingUrl).pathname.split("/").pop(). O token vale 30
minutos.

Antes de responder, grave uma linha no banco deste app: { customerId, token,
expiresAt, status: "pending" }. Você vai precisar dela para casar o resultado
com este cliente depois.

Responda ao frontend APENAS com { token, expiresAt }. Nunca devolva a resposta
crua da Pilot Status e nunca devolva a chave de API.

REQUISITOS CRÍTICOS DE SEGURANÇA — não desvie disto:

- A chave de API da Pilot Status começa com "ps_" e é um segredo de servidor.
  Leia ela SOMENTE de uma variável de ambiente de servidor chamada
  PILOT_TENANT_KEY.
- NUNCA coloque a chave em código de frontend, e NUNCA use prefixo público no
  nome da variável: nem VITE_, nem NEXT_PUBLIC_, nem REACT_APP_, nem PUBLIC_.
  Esses prefixos embutem o valor no bundle do browser, onde qualquer usuário lê.
- NUNCA chame pilotstatus.com.br a partir de código do browser. O CORS da API é
  uma allowlist estrita dos domínios da própria Pilot Status, então uma
  requisição do browser a partir da origem deste app é bloqueada. Toda chamada
  à Pilot Status passa por este backend.
- Não registre em log a chave de API nem o token.

Opcionalmente, o corpo enviado à Pilot Status também aceita um objeto
"branding" que estiliza o botão hospedado. Inclua só se eu pedir:

  "branding": {
    "button": {
      "variant": "facebook",   // ou "dark" | "light" | "outline"
      "label": "Conectar WhatsApp",
      "primaryColor": "#1877F2",
      "textColor": "#FFFFFF",
      "radius": "md",          // "sm" | "md" | "lg" | "pill"
      "size": "md",            // "sm" | "md" | "lg"
      "fullWidth": true
    }
  }

Todos os campos de branding são opcionais. O estilo é aceito SOMENTE dentro
desta requisição assinada — não existe query parameter para isso, então não
tente passar cores ou rótulos na URL do iframe.

Adicione uma seção "Conectar WhatsApp" na página do cliente neste app,
incorporando num iframe o botão de cadastro hospedado da Pilot Status.

Comportamento:

1. Quando o cliente clicar em "Conectar WhatsApp", chame o backend deste
   próprio app: POST /api/pilot/pairing-session com { customerId, customerName }.
   Ele responde { token, expiresAt }.

2. Renderize um iframe com exatamente este src:

   https://connect.pilotstatus.com.br/connect/<token>?embed=1&mode=button&parentOrigin=<origin>

   onde <token> é URL-encoded e <origin> é
   encodeURIComponent(window.location.origin).
   O parâmetro mode=button renderiza somente o botão do Facebook — sem header,
   sem card, com fundo transparente — para encaixar no seu próprio layout.

3. O iframe PRECISA ter este atributo sandbox, exatamente assim:

   sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox"

   allow-popups e allow-popups-to-escape-sandbox são OBRIGATÓRIOS. O popup de
   login do Facebook abre de dentro do iframe. Sem essas duas flags o popup é
   bloqueado silenciosamente: sem erro, sem mensagem no console, o botão
   simplesmente parece não fazer nada. Esta é a falha mais comum desta
   integração.

4. Estilize o iframe: width 100%, border: 0, display: block, e altura inicial
   de 48px. Não defina cor de fundo nele.

5. Registre um listener de "message" no window para receber os eventos do
   iframe. Valide TODA mensagem antes de usar:

   - event.origin precisa ser exatamente "https://connect.pilotstatus.com.br"
   - event.source precisa ser o contentWindow do iframe
   - event.data precisa ser um objeto cuja propriedade "source" seja exatamente
     a string "pilot-status-embed"

   Ignore e retorne cedo em qualquer mensagem que falhe uma dessas três
   checagens.

   O formato da mensagem é:
     { source: "pilot-status-embed", v: 1, type: "<nome do evento>", payload: {...} }

6. Trate o evento "resize": o payload é { height: number }. Ajuste o
   style.height do iframe para essa quantidade de pixels. A página hospedada
   emite esse evento continuamente para o iframe caber no conteúdo sem barra de
   rolagem.

7. Remova o listener quando o componente desmontar.

Não carregue nenhum SDK do Facebook neste app, não chame FB.login em lugar
nenhum e não sirva appId nem config_id para esta página. O iframe hospedado faz
tudo isso num domínio já registrado na Meta. Rodar o SDK no domínio deste app
exigiria registrar este domínio na Meta, o que não é possível aqui.

Não chame pilotstatus.com.br a partir deste código de frontend por motivo
nenhum — nem a API, nem GET /api/health — o CORS bloqueia. Neste fluxo o
frontend não precisa de nenhum dado da Pilot Status para renderizar o botão: o
iframe já vem pronto. A única chamada de rede que o frontend faz é para o
backend deste próprio app, para gerar o token.

Estenda o listener de "message" criado para o iframe de cadastro da Pilot
Status para tratar os três eventos de resultado. Mantenha todas as validações
já existentes de origin, source e "pilot-status-embed" — aplique-as antes de
qualquer coisa abaixo.

Evento: type === "connect:paired"
O cliente concluiu o cadastro com sucesso. O payload é:

  {
    numberId:    string | null,   // o id do número na Pilot Status
    phone:       string | null,   // o número conectado, só dígitos
    displayName: string | null,   // nome de exibição no WhatsApp
    provider:    string | null,   // "META" neste fluxo
    externalRef: string | null,   // o customerId enviado ao gerar o token
    redirectUrl: string | null    // destino opcional após conectar, se você definiu um
  }

Todos os campos podem vir null, então nunca assuma que um valor existe e nunca
quebre por causa de um campo ausente.

Neste evento:
  - Faça POST do payload para o backend deste próprio app, em
    POST /api/pilot/paired.
  - Esconda o iframe e mostre um estado de sucesso com o número.

Evento: type === "connect:error"
Payload é { message: string }. Mostre a mensagem ao cliente e ofereça um botão
de tentar de novo, que gera um token novo e re-renderiza o iframe.

Evento: type === "connect:expired"
O token passou dos 30 minutos de validade. Não reutilize. Mostre "Este link
expirou" e um botão que gera um token novo e re-renderiza o iframe.

Backend: adicione POST /api/pilot/paired.

Ele NÃO pode confiar no externalRef vindo do corpo da requisição para decidir a
qual cliente isso pertence — um browser pode enviar qualquer coisa. Em vez
disso:

  - Identifique o cliente pela sessão autenticada da requisição.
  - Busque a linha pendente que este app gravou quando gerou o token
    (a com status "pending" daquele cliente).
  - Atualize para: { numberId, phone, displayName, provider, status: "connected",
    connectedAt: agora }.
  - Trate o externalRef do payload apenas como conferência cruzada: se não
    bater com o customerId armazenado, registre um aviso e não salve.

Faça este handler idempotente — o mesmo numberId pode chegar duas vezes. Case
pelo numberId e atualize, em vez de inserir uma linha duplicada.

Mantenha a chave de API da Pilot Status fora de tudo isso. Nada nesta etapa
chama pilotstatus.com.br.

Adicione registro de webhook a este app para receber as mensagens de WhatsApp
que chegam em cada número conectado.

Etapa 1 — registre o webhook, do lado do servidor.

Depois que um número for conectado (no handler POST /api/pilot/paired, assim
que o numberId for conhecido), chame a API da Pilot Status pelo backend:

  POST https://pilotstatus.com.br/v1/webhooks
  Headers:
    Content-Type: application/json
    x-api-key: <a variável de ambiente PILOT_TENANT_KEY, só no servidor>
  Body:
    {
      "url": "https://<URL pública deste app>/api/pilot/webhook",
      "whatsappNumberId": "<o numberId vindo do evento paired>",
      "events": ["messages"]
    }

O array "events" é OBRIGATÓRIO na prática. Nada é entregue a menos que events
contenha um nome de evento correspondente ou o coringa "*". Um array vazio, ou
omitir o campo, significa que este app não recebe absolutamente nada — e não
existe erro avisando disso. Sempre envie um array events explícito.

Etapa 2 — receba as entregas.

Adicione uma rota pública: POST /api/pilot/webhook

CRÍTICO — o formato do payload de um número META é o envelope NATIVO da Meta,
não um evento da Pilot Status. Ele é assim:

  {
    "object": "whatsapp_business_account",
    "entry": [
      {
        "id": "<id da waba>",
        "time": 1753027200,
        "changes": [
          { "field": "messages", "value": { ...payload de mensagem da Meta... } }
        ]
      }
    ]
  }

Faça o parse lendo body.entry[0].changes[0].field e ramifique por esse valor.
Mensagens recebidas chegam com field === "messages", com as mensagens em
value.messages[] e os contatos em value.contacts[].

NÃO escreva um handler que procure um evento chamado "message.received". Um
número META NUNCA envia isso. "message.received" pertence a outro tipo de
número, não oficial. Assinar com events: ["*"] também não traduz o payload — em
número META é sempre o envelope nativo da Meta.

Outros pontos para acertar:

- Um webhook criado via POST /v1/webhooks não tem secret, então essas entregas
  NÃO trazem header de assinatura — não escreva verificação de assinatura e não
  assuma que a requisição está autenticada. (Se um secret for definido depois no
  webhook, as entregas passam a incluir um header x-pilot-status-signature com um
  HMAC-SHA256 do corpo cru da requisição; só verifique isso depois de ter de fato
  definido um secret.) Use um segmento imprevisível no path da URL do webhook, ou
  uma allowlist de IP, se precisar endurecer isso.
- Responda HTTP 200 imediatamente e processe de forma assíncrona. Entregas com
  falha são retentadas 5 vezes com backoff exponencial a partir de 5 segundos,
  então handlers lentos ou que falham geram duplicatas.
- Faça o handler idempotente — deduplique pelo id da mensagem no payload da
  Meta.
- A URL do webhook precisa ser publicamente acessível por HTTPS. Uma URL de
  localhost ou só de preview nunca vai receber nada.