# 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](/docs/guides/whatsapp/webhooks/lifecycle). Las reacciones tienen su propio historial, descrito en [Eventos de reacciones](/docs/guides/whatsapp/events/reactions). ## Eventos del ciclo de vida Los eventos aparecen en orden cronológico. Un mensaje saliente puede detenerse en [`whatsapp.failed` o `whatsapp.rejected`](#eventos-de-fallo), 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}`](/docs/api/reference/get-whatsapp-message) para ver cuánto costó. Consulta [Coste y facturación](/docs/guides/whatsapp/sending-whatsapp#cost-and-billing). [Marcar un mensaje entrante como leído](/docs/guides/whatsapp/mark-message-as-read) 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](/docs/guides/whatsapp/sending-whatsapp#cost-and-billing). 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](/docs/guides/whatsapp/opt-outs), 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`: **TypeScript** ```typescript const { data } = await bird.whatsapp.listEvents("wa_abc123"); for (const event of data) console.log(event.type, event.occurred_at); ``` Examples: [TypeScript](/es-es/documentacion/guides/whatsapp/events/lifecycle.ts.md) · [Python](/es-es/documentacion/guides/whatsapp/events/lifecycle.py.md) · [Go](/es-es/documentacion/guides/whatsapp/events/lifecycle.go.md) · [PHP](/es-es/documentacion/guides/whatsapp/events/lifecycle.php.md) · [CLI](/es-es/documentacion/guides/whatsapp/events/lifecycle.cli.md) · [MCP](/es-es/documentacion/guides/whatsapp/events/lifecycle.mcp.md) · [cURL](/es-es/documentacion/guides/whatsapp/events/lifecycle.curl.md) Un mensaje que fue aceptado, enviado, entregado y leído devuelve cuatro 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" } ] } ``` 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](/docs/guides/whatsapp/message-log) muestra cuando abres un mensaje. ![La hoja de detalle de mensaje WhatsApp en el panel de Bird, abierta para un mensaje bird_delivery_update entregado: la pestaña Events mostrando la línea de tiempo del ciclo de vida por mensaje con Accepted, Sent, Delivered y Read, cada uno con su tiempo transcurrido y marca temporal, sobre la lista de mensajes atenuada](/images/docs/dashboard-whatsapp-detail.png) ## Próximos pasos - [Webhooks del ciclo de vida de mensajes](/docs/guides/whatsapp/webhooks/lifecycle): recibe cada evento a medida que ocurre - [Eventos de reacciones](/docs/guides/whatsapp/events/reactions): lee las reacciones actuales y el registro de reacciones - [Marcar mensaje como leído](/docs/guides/whatsapp/mark-message-as-read): confirma un mensaje entrante y muestra escritura - [Registro de WhatsApp](/docs/guides/whatsapp/message-log): la vista por mensaje que muestra esta línea de tiempo - [Envío de mensajes WhatsApp](/docs/guides/whatsapp/sending-whatsapp): donde comienza el ciclo de vida de un mensaje ## 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)