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.
| Evento | Dispara quando |
|---|---|
| whatsapp.accepted | Bird aceita uma solicitação de envio |
| whatsapp.sent | Bird entrega a mensagem à rede WhatsApp |
| whatsapp.delivered | WhatsApp confirma a entrega no dispositivo do destinatário |
| whatsapp.read | O destinatário abre a mensagem |
| whatsapp.failed | A mensagem falha na entrega |
| whatsapp.rejected | Bird recusa a mensagem antes de enviá-la |
| whatsapp.received | Um contato envia uma mensagem a você |
| whatsapp.reacted | Um contato adiciona, altera ou remove uma reação |
| whatsapp_suppression.created | Uma supressão é aberta no seu espaço de trabalho |
| whatsapp.group.join_request_created | Alguém solicita participar de um grupo |
| whatsapp.group.join_request_revoked | Alguém cancela a solicitação de participar de um grupo |
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.
Exemplo de código
{
"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 do ciclo de vida da mensagem: payloads de entrega e de mensagem recebida
- Eventos do ciclo de vida: consulte a mesma linha do tempo pela API
- Guia de webhooks: endpoints, assinaturas, tentativas de reenvio e o catálogo completo de eventos
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.
Assista ao guiaConnecting WhatsApp to Bird: from buying a number to a live channelEntenda o conceitoWhat is the 24-hour customer service window on WhatsApp?Use a ferramentaWhatsApp message builderExplore a funcionalidadeWhatsApp
Experimente na prática e obtenha um resumo de implementação