Webhooks de status de mensagem WhatsApp
Cada mudança no status de uma mensagem enviada pode ser entregue ao seu endpoint no momento em que acontece. Todo payload usa o envelope de evento WhatsApp e inclui os campos presentes em todo evento de mensagem.
Eventos de entrega
whatsapp.accepted, whatsapp.sent, whatsapp.delivered e whatsapp.read contêm apenas os campos comuns a todos os eventos de mensagem. O guia Eventos de status de mensagem explica o significado de cada um e quando whatsapp.delivered é omitido.
{
"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"
}whatsapp.failed e whatsapp.rejected também incluem um objeto error com um Bird code estável, um description legível, um meta_error_code opcional e occurred_at. Consulte eventos de falha para saber o que diferencia os dois. Em uma falha WhatsApp reportada, description é a explicação do próprio WhatsApp. Uma mensagem de serviço cuja janela de atendimento ao cliente fechou entre a aceitação e o envio falha assim:
{
"data": {
"direction": "outbound",
"error": {
"code": "service_window_expired",
"description": "Message failed to send because more than 24 hours have passed since the customer last replied to this number.",
"meta_error_code": "131047",
"occurred_at": "2026-07-23T14:51:40.201Z"
},
"from": { "phone_number": "+13124495569" },
"metadata": null,
"tags": null,
"to": { "phone_number": "+14155550100" },
"whatsapp_id": "wam_01ky7qbvswf3fvyaw3az90391c",
"workspace_id": "ws_01ky7m235keycbnwyajabe1a6b"
},
"timestamp": "2026-07-23T14:51:40.201Z",
"type": "whatsapp.failed"
}Marcar uma mensagem recebida como lida registra whatsapp.read na linha do tempo da mensagem, mas não emite um webhook.
Próximos passos
- Webhooks de mensagens recebidas: processe as mensagens dos seus contatos
- Webhooks de reações: processe as reações com emojis de um contato
- Guia de webhooks: configure endpoints, verifique assinaturas e trate novas tentativas
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico.