curl -X POST "https://pilotstatus.com.br/v1/numbers/remote-pairing" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_sua_chave_tenant" \
  -d '{
    "provider": "META",
    "metaFlow": "embedded",
    "name": "Cliente João",
    "externalRef": "crm-org-42",
    "branding": {
      "button": {
        "variant": "whatsapp",
        "label": "Conectar meu WhatsApp",
        "icon": "whatsapp",
        "radius": "pill",
        "size": "lg",
        "height": 56,
        "fullWidth": true
      }
    }
  }'

<div id="connect-slot"></div>

<script>
  // connectUrl = a remotePairingUrl que o SEU backend devolveu (nunca a chave ps_).
  async function embedConnect() {
    const { connectUrl } = await fetch("/api/onboarding/start", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ name: "Cliente João", externalRef: "crm-org-42" }),
    }).then((r) => r.json());

    const src =
      connectUrl +
      "?embed=1&mode=button&parentOrigin=" +
      encodeURIComponent(location.origin);

    const iframe = document.createElement("iframe");
    iframe.src = src;
    iframe.sandbox =
      "allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox allow-forms";
    iframe.style.cssText = "width:100%;border:0;display:block";
    iframe.style.height = "60px"; // ajustada pelo evento `resize`
    document.getElementById("connect-slot").appendChild(iframe);
  }
  embedConnect();
</script>

<script>
  const CONNECT_ORIGIN = "https://connect.pilotstatus.com.br";
  // numberId veio junto com o connectUrl (seu backend decodificou a claim do JWT).
  let conectado = false;

  window.addEventListener("message", (event) => {
    // Dois cheques obrigatórios: a origem tem que ser o host do connect, e
    // toda mensagem carrega o marcador `source: "pilot-status-embed"`. Sem o
    // segundo, qualquer script na sua página poderia forjar um connect:paired.
    if (event.origin !== CONNECT_ORIGIN) return;
    const msg = event.data;
    if (!msg || msg.source !== "pilot-status-embed") return;

    // Envelope: { source, v, type, payload }. Só o `type` fica no topo; o
    // resto vem em `payload`.
    const p = msg.payload || {};
    switch (msg.type) {
      case "connect:paired": {
        // p = { numberId, phone, displayName, provider, externalRef, redirectUrl }
        // Cruze pelo externalRef que VOCÊ passou ao gerar o link.
        conectado = true;
        salvarNumeroConectado(p.numberId, p.externalRef);
        break;
      }
      case "connect:expired":
        // Token de 30 min expirou — gere um novo link e re-embeta.
        break;
      case "connect:error":
        // Chega também quando a pessoa CANCELA ou fecha o popup do Facebook.
        // O botão continua na tela para ela tentar de novo — aqui só anote.
        // Cancelou o popup? Ela ainda pode clicar de novo — só limpe quando
        // tiver certeza de que foi embora (ex.: fechou o modal, saiu da página).
        console.error(p.message);
        break;
      case "resize":
        // Ajuste a altura do iframe conforme a página hospedada cresce.
        document.querySelector("#connect-slot iframe").style.height = p.height + "px";
        break;
    }
  });

  // Chame quando a pessoa realmente foi embora: você fechou o modal,
  // ela saiu da página, ou você desistiu da sessão.
  async function encerrarOnboarding(numberId) {
    if (conectado) return; // conectou: o número é real, não apague.
    // Só o SEU backend tem a chave ps_ — é ele que chama DELETE /v1/numbers/{id}.
    await fetch("/api/onboarding/abandon", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ numberId }),
    });
  }
</script>

// POST /api/onboarding/abandon  { numberId }
// BASE e TENANT_KEY são as mesmas constantes do "Backend de exemplo", abaixo.
app.post("/api/onboarding/abandon", async (req, res) => {
  const { numberId } = req.body || {};
  const r = await fetch(`${BASE}/v1/numbers/${numberId}`, {
    method: "DELETE",
    headers: { "x-api-key": TENANT_KEY },
  });
  // 200 { ok: true } — slot devolvido. 404 = já não existe: nada a fazer.
  res.status(r.ok ? 200 : r.status).json(await r.json().catch(() => ({})));
});

curl -X POST "https://pilotstatus.com.br/v1/webhooks" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ps_sua_chave_tenant" \
  -d '{
    "url": "https://seu-crm.com/hooks/whatsapp",
    "whatsappNumberId": "<numberId>",
    "events": ["*"]
  }'

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "987654321098765",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": { "display_phone_number": "5511999999999", "phone_number_id": "123456789012345" },
            "messages": [{ "from": "5585984387245", "id": "wamid...", "type": "text", "text": { "body": "Oi" } }]
          }
        }
      ]
    }
  ]
}