# Eventos do ciclo de vida de mensagens WhatsApp Bird registra **eventos** para mensagens WhatsApp de entrada e de saída. Uma linha do tempo de saída mostra o que aconteceu depois que um envio retornou `202`: aceitação, repasse para WhatsApp, entrega, leitura ou falha. Uma linha do tempo de entrada registra quando Bird recebeu a mensagem. Esta página aborda a leitura dessa linha do tempo pela API. Para que Bird envie cada evento ao seu endpoint conforme ele acontece, consulte [Webhooks do ciclo de vida de mensagens](/docs/guides/whatsapp/webhooks/lifecycle). Reações têm seu próprio histórico, coberto em [Eventos de reação](/docs/guides/whatsapp/events/reactions). ## Eventos do ciclo de vida Os eventos aparecem em ordem cronológica. Uma mensagem de saída pode parar em [`whatsapp.failed` ou `whatsapp.rejected`](#eventos-de-falha), e o evento `whatsapp.read` aparece somente se o destinatário abrir a mensagem. Uma linha do tempo de entrada começa com `whatsapp.received` e pode registrar `whatsapp.read` depois que seu espaço de trabalho marca a mensagem como lida. | Evento | Significado | | -------------------- | ----------------------------------------------------------------- | | `whatsapp.accepted` | Bird aceitou a solicitação de envio. Isso é o que `202` reportou. | | `whatsapp.sent` | Bird repassou a mensagem para a rede WhatsApp. | | `whatsapp.delivered` | WhatsApp confirmou a entrega no dispositivo do destinatário. | | `whatsapp.read` | O destinatário abriu a mensagem. | | `whatsapp.failed` | A mensagem não foi entregue. `error.code` indica o que a impediu. | | `whatsapp.rejected` | Bird recusou a mensagem antes de enviá-la. Não houve cobrança. | | `whatsapp.received` | Bird recebeu uma mensagem de entrada de um contato. | Callbacks `delivered` ou `read` aplicáveis podem acionar a parte do preço cobrada pela Meta. Payloads de eventos WhatsApp não carregam custo. Leia a mensagem de volta com [`GET /v1/whatsapp/messages/{message_id}`](/docs/api/reference/get-whatsapp-message) para ver quanto ela custou. Consulte [Custo e cobrança](/docs/guides/whatsapp/sending-whatsapp#cost-and-billing). [Marcar uma mensagem de entrada como lida](/docs/guides/whatsapp/mark-message-as-read) registra `whatsapp.read` na linha do tempo dela, mas não emite um webhook de confirmação de leitura. A mensagem de entrada mantém seu status `received` e registra `read_at` depois que WhatsApp aceita a confirmação. `whatsapp.read` **não** altera o `status` da mensagem. Uma mensagem entregue permanece `delivered`; a mensagem também registra a leitura em `read_at`. **`whatsapp.delivered` pode ser totalmente ignorado.** Quando o destinatário já está com o chat aberto no dispositivo, a Meta reporta a leitura sem nunca reportar uma entrega, então a linha do tempo mostra `whatsapp.accepted` → `whatsapp.sent` → `whatsapp.read` sem `whatsapp.delivered` entre eles. Trate `read` como prova de entrega: um consumidor que espera por `delivered` antes de considerar a mensagem entregue vai travar exatamente nos destinatários que a viram mais rápido, e um que calcula a taxa de entrega apenas a partir de `delivered` a subreporta. O `status` da mensagem permanece `sent` nesse caso, já que apenas um recibo de entrega o avança. Um callback somente de leitura ainda pode acionar a taxa aplicável da Meta. Bird usa uma única identidade de taxa nos caminhos de entrega e leitura; a ausência do evento de entrega não implica um componente Meta gratuito. Consulte [Custo e cobrança](/docs/guides/whatsapp/sending-whatsapp#cost-and-billing). 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 em vez de um erro. ## Eventos de falha `whatsapp.failed` e `whatsapp.rejected` são terminais. Uma **rejeição** significa que Bird bloqueou a mensagem antes de enviá-la para WhatsApp, então ela não foi cobrada. As causas incluem um [destinatário suprimido ou que cancelou a inscrição](/docs/guides/whatsapp/opt-outs), saldo insuficiente na carteira ou um destino sem preço configurado. Uma **falha** significa que a mensagem não foi entregue, e `error.code` indica quem decidiu isso. A maioria dos códigos carrega o veredito de WhatsApp, mapeado a partir do código que ele reportou. `internal_error` é a exceção: registra uma credencial de remetente utilizável ausente ou tentativas de processamento esgotadas. Uma tentativa de transporte incerta não prova que a Meta nunca recebeu a solicitação. `meta_error_code` contém o código de WhatsApp quando disponível, e uma falha `internal_error` não tem nenhum por definição. Ambos os eventos contêm um objeto `error` com um Bird `code` estável, um `description` legível por humanos, um `meta_error_code` opcional e `occurred_at`. O objeto aparece em registros API e payloads de webhook apenas para esses tipos de evento. ## Lendo eventos da API `GET /v1/whatsapp/messages/{message_id}/events` retorna a linha do tempo em ordem cronológica. A lista limitada não é paginada. Ler eventos requer uma chave API com `whatsapp:read`: **TypeScript** ```typescript const { data } = await bird.whatsapp.listEvents("wa_abc123"); for (const event of data) console.log(event.type, event.occurred_at); ``` Examples: [TypeScript](/pt-br/documentacao/guides/whatsapp/events/lifecycle.ts.md) · [Python](/pt-br/documentacao/guides/whatsapp/events/lifecycle.py.md) · [Go](/pt-br/documentacao/guides/whatsapp/events/lifecycle.go.md) · [PHP](/pt-br/documentacao/guides/whatsapp/events/lifecycle.php.md) · [CLI](/pt-br/documentacao/guides/whatsapp/events/lifecycle.cli.md) · [MCP](/pt-br/documentacao/guides/whatsapp/events/lifecycle.mcp.md) · [cURL](/pt-br/documentacao/guides/whatsapp/events/lifecycle.curl.md) Uma mensagem que foi aceita, enviada, entregue e lida retorna quatro eventos: ```json { "data": [ { "id": "ev_01ky7q6a1fejfbvs0myn41hj41", "occurred_at": "2026-07-23T14:48:34.71Z", "type": "whatsapp.accepted" }, { "id": "ev_01ky7q6a2denvtd6jg1vqwmg13", "occurred_at": "2026-07-23T14:48:35.671Z", "type": "whatsapp.sent" }, { "id": "ev_01ky7q6a2zff9r2qm74mmg1g6z", "occurred_at": "2026-07-23T14:48:36.642Z", "type": "whatsapp.delivered" }, { "id": "ev_01ky7q6c21frssf0vj8h50qysw", "occurred_at": "2026-07-23T14:48:38.65Z", "type": "whatsapp.read" } ] } ``` Passe `type` para retornar um tipo de evento público exato, como `?type=whatsapp.failed` ou `?type=whatsapp.read`. Omita para a linha do tempo completa. Essa mesma linha do tempo é o que a página de [log WhatsApp](/docs/guides/whatsapp/message-log) renderiza quando você abre uma mensagem. ![A ficha de detalhes da mensagem WhatsApp no painel Bird, aberta para uma mensagem bird_delivery_update entregue: a aba Eventos mostrando a linha do tempo do ciclo de vida por mensagem com Aceita, Enviada, Entregue e Lida, cada uma com seu tempo decorrido e carimbo de data/hora, sobre a lista de mensagens esmaecida](/images/docs/dashboard-whatsapp-detail.png) ## Próximos passos - [Webhooks do ciclo de vida de mensagens](/docs/guides/whatsapp/webhooks/lifecycle): receba cada evento conforme ele acontece - [Eventos de reação](/docs/guides/whatsapp/events/reactions): leia as reações atuais e o log de reações - [Marcar mensagem como lida](/docs/guides/whatsapp/mark-message-as-read): confirme uma mensagem de entrada e mostre indicador de digitação - [Log WhatsApp](/docs/guides/whatsapp/message-log): a visualização por mensagem que renderiza essa linha do tempo - [Enviando mensagens WhatsApp](/docs/guides/whatsapp/sending-whatsapp): onde o ciclo de vida de uma mensagem começa ## Related resources - [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video) - [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer) - [WhatsApp message builder](/tools/whatsapp-message-builder) (tool) - [WhatsApp](/whatsapp-api) (product) [Get an implementation brief](/learn/workspace?topic=whatsapp)