Eventos del ciclo de vida de mensajes WhatsApp
Bird registra eventos para mensajes WhatsApp entrantes y salientes. Una línea de tiempo saliente muestra lo que ocurrió después de que un envío devolvió 202: aceptación, traspaso a WhatsApp, entrega, lectura o fallo. Una línea de tiempo entrante registra cuándo Bird recibió el mensaje.
Esta página cubre la lectura de esa línea de tiempo a través de API. Para que Bird envíe cada evento a tu endpoint a medida que ocurre, consulta Webhooks del ciclo de vida de mensajes. Las reacciones tienen su propio historial, descrito en Eventos de reacciones.
Eventos del ciclo de vida
Los eventos aparecen en orden cronológico. Un mensaje saliente puede detenerse en whatsapp.failed o whatsapp.rejected, y su evento whatsapp.read aparece solo si el destinatario abre el mensaje. Una línea de tiempo entrante comienza con whatsapp.received y puede registrar whatsapp.read después de que tu espacio de trabajo marque el mensaje como leído.
| Evento | Significado |
|---|---|
| whatsapp.accepted | Bird aceptó la solicitud de envío. Esto es lo que reportó 202. |
| whatsapp.sent | Bird entregó el mensaje a la red de WhatsApp. |
| whatsapp.delivered | WhatsApp confirmó la entrega al dispositivo del destinatario. |
| whatsapp.read | El destinatario abrió el mensaje. |
| whatsapp.failed | El mensaje no se entregó. error.code indica qué lo impidió. |
| whatsapp.rejected | Bird rechazó el mensaje antes de enviarlo. No se cobró. |
| whatsapp.received | Bird recibió un mensaje entrante de un contacto. |
Los callbacks delivered o read aplicables pueden activar la parte del precio correspondiente a Meta. Los payloads de eventos WhatsApp no incluyen coste. Lee el mensaje con GET /v1/whatsapp/messages/{message_id} para ver cuánto costó. Consulta Coste y facturación.
Marcar un mensaje entrante como leído registra whatsapp.read en su línea de tiempo, pero no emite un webhook de confirmación de lectura. El mensaje entrante mantiene su estado received y registra read_at después de que WhatsApp acepta la confirmación.
whatsapp.read no cambia el status del mensaje. Un mensaje entregado permanece como delivered; el mensaje también registra la lectura en read_at.
whatsapp.delivered puede omitirse por completo. Cuando el destinatario ya tiene el chat abierto en su dispositivo, Meta reporta la lectura sin reportar nunca una entrega, así que la línea de tiempo se lee whatsapp.accepted → whatsapp.sent → whatsapp.read sin whatsapp.delivered en medio. Trata read como prueba de entrega: un consumidor que espera delivered antes de considerar el mensaje llegado se quedará esperando exactamente en los destinatarios que lo vieron más rápido, y uno que calcule una tasa de entrega solo a partir de delivered la infravalora. El status del mensaje permanece como sent en este caso, ya que solo un acuse de entrega lo avanza.
Un callback de solo lectura puede aun así activar la tarifa aplicable de Meta. Bird usa una identidad de tarifa única en las rutas de entrega y lectura; la ausencia del evento de entrega no implica un componente Meta gratuito. Consulta Coste y facturación.
La lista de tipos de evento es abierta: pueden añadirse nuevos tipos con el tiempo, así que trata un valor no reconocido como un evento futuro en lugar de un error.
Eventos de fallo
whatsapp.failed y whatsapp.rejected son terminales. Un rechazo significa que Bird detuvo el mensaje antes de enviarlo a WhatsApp, por lo que no se cobró. Las causas incluyen un destinatario suprimido o dado de baja, saldo insuficiente en la cartera o un destino sin precio configurado. Un fallo significa que el mensaje no se entregó, y error.code indica quién lo decidió. La mayoría de los códigos contienen el veredicto de WhatsApp, mapeado a partir del código que reportó. internal_error es la excepción: registra una credencial de remitente no utilizable o reintentos de procesamiento agotados. Un intento de transporte incierto no demuestra que Meta nunca recibió la solicitud. meta_error_code contiene el código de WhatsApp cuando está disponible, y un fallo internal_error no tiene ninguno por definición.
Ambos eventos contienen un objeto error con un Bird code estable, un description legible, un meta_error_code opcional y occurred_at. El objeto aparece en los registros API y en los payloads de webhooks solo para estos tipos de evento.
Lectura de eventos desde API
GET /v1/whatsapp/messages/{message_id}/events devuelve la línea de tiempo en orden cronológico. La lista acotada no está paginada. Leer eventos requiere una clave API con 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"Un mensaje que fue aceptado, enviado, entregado y leído devuelve cuatro eventos:
Ejemplo 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"
}
]
}Pasa type para obtener un tipo de evento público exacto, como ?type=whatsapp.failed o ?type=whatsapp.read. Omítelo para la línea de tiempo completa.
La misma línea de tiempo es lo que la página del registro de WhatsApp muestra cuando abres un mensaje.
Próximos pasos
- Webhooks del ciclo de vida de mensajes: recibe cada evento a medida que ocurre
- Eventos de reacciones: lee las reacciones actuales y el registro de reacciones
- Marcar mensaje como leído: confirma un mensaje entrante y muestra escritura
- Registro de WhatsApp: la vista por mensaje que muestra esta línea de tiempo
- Envío de mensajes WhatsApp: donde comienza el ciclo de vida de un mensaje
Recursos relacionados
Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.
Ver la guíaConnecting WhatsApp to Bird: from buying a number to a live channelComprender el conceptoWhat is the 24-hour customer service window on WhatsApp?Usar la herramientaWhatsApp message builderExplorar la funcionalidadWhatsApp
Prueba el ejercicio y obtén un resumen de implementación