Webhooks do WhatsApp

Bird envia a atividade de WhatsApp ao seu endpoint em tempo real, dispensando a necessidade de polling. Inscreva-se pela página Webhooks ou com POST /v1/webhooks. O Guia de webhooks cobre endpoints, verificação de assinatura e tentativas de reenvio.

Eventos disponíveis para inscrição

Cada evento contém um link para seu payload.

A lista de tipos de evento é aberta: novos tipos podem ser adicionados com o tempo, então trate um valor não reconhecido como um evento futuro, não como um erro.

O envelope do evento

Todo evento WhatsApp usa o envelope de webhook padrão: um type, um timestamp e um objeto data específico do tipo.

{
  "data": {
    "direction": "outbound",
    "from": { "phone_number": "+13124495569" },
    "metadata": { "session_id": "sess_4821" },
    "tags": [{ "name": "flow", "value": "login-otp" }],
    "to": { "phone_number": "+14155550100" },
    "whatsapp_id": "wam_01ky7qbvswf3fvyaw3az90391c",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b"
  },
  "timestamp": "2026-07-23T14:51:39.913Z",
  "type": "whatsapp.delivered"
}

Campos presentes em todo evento de mensagem

Cada payload de webhook WhatsApp para uma mensagem inclui whatsapp_id, workspace_id, direction, from, to, tags e metadata. Os eventos de reação, supressão e grupo não se referem a uma mensagem, então cada um tem sua própria estrutura, descrita na respectiva página.

• Endereços: from e to podem incluir um phone_number E.164, um ID de usuário com escopo de negócio da Meta em bsuid, ou ambos. Uma mensagem recebida de um usuário do WhatsApp também traz o perfil que ele publica, em username e display_name.
• tags e metadata são null quando o envio não incluiu nenhum.
• in_reply_to_message_id aparece em todo evento de saída de uma mensagem enviada como resposta, de whatsapp.accepted até whatsapp.read, whatsapp.failed ou whatsapp.rejected, indicando a mensagem respondida.

Payloads de evento não incluem custo. Consulte a mensagem com GET /v1/whatsapp/messages/{message_id} para ver quanto custou.

Próximos passos

• Webhooks de status de mensagem: payloads de entrega e falha
• Webhooks de mensagem recebida: o payload whatsapp.received
• Webhooks de reação: o payload whatsapp.reacted
• Guia de webhooks: endpoints, assinaturas, tentativas de reenvio e o catálogo completo de eventos