Webhooks de estado de mensaje de WhatsApp

Cada cambio en el estado de un mensaje saliente puede enviarse a tu endpoint en el momento en que ocurre. Cada payload usa la envoltura de evento WhatsApp e incluye los campos que lleva cada evento de mensaje.

Eventos de entrega

whatsapp.accepted, whatsapp.sent, whatsapp.delivered y whatsapp.read solo llevan los campos que lleva cada evento de mensaje. Eventos de ciclo de vida explica qué significa cada uno y cuándo se omite whatsapp.delivered.

Ejemplo 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 y whatsapp.rejected también llevan un objeto error con un Bird code estable, un description legible, un meta_error_code opcional y occurred_at. Consulta eventos de fallo para ver qué distingue a los dos. En un fallo reportado por WhatsApp, description es la explicación propia de WhatsApp. Un mensaje de servicio cuya ventana de atención al cliente se cerró entre la aceptación y el envío falla de esta forma:

Ejemplo 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 un mensaje entrante como leído registra whatsapp.read en la línea de tiempo del mensaje, pero no emite un webhook.

Próximos pasos

Webhooks de mensajes entrantes: el payload whatsapp.received de un mensaje que te envía un contacto
Webhooks de reacciones: las reacciones de un contacto llegan por separado
Eventos de estado de mensaje: consulta la línea de tiempo de un mensaje a través de la API

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 channel Comprender el conceptoWhat is the 24-hour customer service window on WhatsApp?Usar la herramientaWhatsApp message builder Explorar la funcionalidadWhatsApp

Prueba el ejercicio y obtén un resumen de implementación