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 presentes em todo evento de mensagem. Eventos de ciclo de vida explica o significado de cada um e quando whatsapp.delivered é omitido.

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"
}

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:

Exemplo de código

{
  "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 mensagem recebida: o payload whatsapp.received de uma mensagem que um contato envia para você
Webhooks de reação: as reações de um contato chegam separadamente
Eventos de status de mensagem: consulte a linha do tempo de uma mensagem pela API

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 channel Entenda o conceitoWhat is the 24-hour customer service window on WhatsApp?Use a ferramentaWhatsApp message builder Explore a funcionalidadeWhatsApp

Experimente na prática e obtenha um resumo de implementação