MODULO 3.2

🔌 Integracao Cloud API

Webhooks, envios, templates, idempotencia e observabilidade — o que muda no codigo com BSUID.

1

📥 Webhook recebido

Webhook entrega messages[] e contacts[]. Pegue BSUID no contacts.

POST /webhooks/whatsapp HTTP/1.1
Content-Type: application/json
X-Hub-Signature-256: sha256=...

{
  "entry": [{
    "id": "<WABA_ID>",
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "metadata": {
          "display_phone_number": "5511...",
          "phone_number_id": "<PHONE_NUMBER_ID>"
        },
        "contacts": [{
          "user_id": "<BSUID>",
          "profile": { "name": "Maria" }
        }],
        "messages": [{
          "from": "5511...",
          "id": "wamid.HBgL...",
          "timestamp": "1716...",
          "type": "text",
          "text": { "body": "Ola" }
        }]
      },
      "field": "messages"
    }]
  }]
}

⚠️ Quando user_id NAO chega

Versoes antigas da API podem nao expor o campo. Cheque sempre a versao do endpoint configurada. Sem BSUID, mantenha wa_id como fallback ate atualizar.

2

📤 Enviar mensagem com BSUID

Send Message API aceita BSUID como destinatario. Dentro da janela de 24h sem template.

POST /v22.0/<PHONE_NUMBER_ID>/messages
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<BSUID_DO_USUARIO>",
  "type": "text",
  "text": { "body": "Olá! Como podemos ajudar?" }
}

⏰ Sessao de 24h

Apos a ultima mensagem do usuario, voce tem 24h para responder com qualquer conteudo. Depois disso, so templates aprovados.

3

🪪 Templates (HSM)

Templates de marketing/utility passam a aceitar BSUID. Variaveis funcionam igual.

{
  "messaging_product": "whatsapp",
  "to": "<BSUID>",
  "type": "template",
  "template": {
    "name": "promo_inverno_2026",
    "language": { "code": "pt_BR" },
    "components": [{
      "type": "body",
      "parameters": [
        { "type": "text", "text": "Maria" },
        { "type": "text", "text": "20%" }
      ]
    }]
  }
}

📜 Opt-in continua obrigatorio

LGPD nao mudou — voce precisa de consentimento valido antes de enviar templates de marketing, com BSUID ou nao.

4

🔁 Idempotencia

Webhooks duplicam por retry. Dedupe por (business_id, bsuid, message_id).

-- Insert idempotente
INSERT INTO mensagens_wa
  (business_id, bsuid, message_id, direction, body, created_at)
VALUES
  ($1, $2, $3, 'in', $4, NOW())
ON CONFLICT (business_id, message_id) DO NOTHING;

✓ Beneficio

Retries da Meta nao geram duplicacao no seu banco. Conta de mensagens fica precisa.

5

🧪 Testes e sandbox

A Cloud API entrega numero de teste gratis. Use ANTES de subir prod.

1

Numero de teste no Meta for Developers

Cada app ganha um numero teste. Voce adiciona ate 5 destinatarios de teste.

2

Webhook tunnel local (ngrok)

Tunelize seu localhost para receber webhooks reais durante desenvolvimento.

3

Fixtures de BSUID para testes unitarios

Crie payloads fake de webhook com BSUID consistente — rode em CI sem precisar de WhatsApp real.

6

📈 Observabilidade

Logs com {business_id, bsuid, message_id, status} permitem debug sem expor PII.

{
  "ts": "2026-05-21T18:30:00Z",
  "level": "info",
  "event": "wa.message.received",
  "business_id": "b_8f3a2c",
  "bsuid": "7a3f2b9c1e...",
  "message_id": "wamid.HBgL...",
  "direction": "in",
  "type": "text"
}

✓ Vantagens

  • BSUID e pseudonimizado — menor risco em SIEM
  • Permite filtrar por cliente sem PII
  • Diferencia clientes da mesma empresa sem precisar de telefone

🎓 Resumo

✓
Webhook: capture BSUID em contacts[].user_id.
✓
Envio: use BSUID como `to`, sessao de 24h ou templates aprovados.
✓
Idempotencia: (business_id, message_id) UNIQUE.
✓
Observabilidade: logue BSUID, evite telefone em logs.

Proximo Modulo:

3.3 — CRM e conformidade

← Modulo AnteriorProximo Modulo →