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. Reações têm seu próprio histórico, coberto em Eventos de reação.
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, 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} para ver quanto ela custou. Consulte Custo e cobrança.
Marcar uma mensagem de entrada como lida 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.
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, 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:
const { data } = await bird.whatsapp.listEvents("wa_abc123");
for (const event of data) console.log(event.type, event.occurred_at);events = client.whatsapp.list_events("wa_abc123")
for event in events.data:
print(event.type, event.occurred_at)events, err := client.Whatsapp.ListEvents(context.Background(), "wam_01krdgeqcxet5s7t44vh8rt9mg", bird.WhatsappListEventsParams{})
if err != nil {
log.Fatal(err)
}
for _, e := range events.Data {
fmt.Println(e.Id, e.Type)
}$events = $bird->whatsapp->listEvents('wamid_01krdgeqcxet5s7t44vh8rt9mg');
foreach ($events->getData() ?? [] as $event) {
echo $event->getType(), ' ', $event->getId(), "\n";
}bird whatsapp list-events <message-id>curl https://us1.platform.bird.com/v1/whatsapp/messages/wam_.../events \
-H "Authorization: Bearer $BIRD_API_KEY"Uma mensagem que foi aceita, enviada, entregue e lida retorna quatro eventos:
Exemplo de código
{
"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 renderiza quando você abre uma mensagem.
Próximos passos
- Webhooks do ciclo de vida de mensagens: receba cada evento conforme ele acontece
- Eventos de reação: leia as reações atuais e o log de reações
- Marcar mensagem como lida: confirme uma mensagem de entrada e mostre indicador de digitação
- Log WhatsApp: a visualização por mensagem que renderiza essa linha do tempo
- Enviando mensagens WhatsApp: onde o ciclo de vida de uma mensagem começa
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