# Webhooks de WhatsApp

Bird envía la actividad de WhatsApp a tu endpoint en tiempo real, así no necesitas hacer polling. Suscríbete desde la página [**Webhooks**](https://bird.com/dashboard/w/webhooks) o con [`POST /v1/webhooks`](/docs/api/reference/create-webhook). La [guía de webhooks](/docs/guides/webhooks) cubre endpoints, verificación de firma y reintentos.

## Eventos a los que puedes suscribirte

Cada evento enlaza a su payload.

| Evento                                                                                              | Se dispara cuando                                            |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| [`whatsapp.accepted`](/docs/guides/whatsapp/webhooks/lifecycle#delivery-events)                     | Bird acepta una solicitud de envío saliente                  |
| [`whatsapp.sent`](/docs/guides/whatsapp/webhooks/lifecycle#delivery-events)                         | Bird entrega el mensaje a la red de WhatsApp                 |
| [`whatsapp.delivered`](/docs/guides/whatsapp/webhooks/lifecycle#delivery-events)                    | WhatsApp confirma la entrega al dispositivo del destinatario |
| [`whatsapp.read`](/docs/guides/whatsapp/webhooks/lifecycle#delivery-events)                         | El destinatario abre el mensaje                              |
| [`whatsapp.failed`](/docs/guides/whatsapp/webhooks/lifecycle#delivery-events)                       | El mensaje no se puede entregar                              |
| [`whatsapp.rejected`](/docs/guides/whatsapp/webhooks/lifecycle#delivery-events)                     | Bird rechaza el mensaje antes de enviarlo                    |
| [`whatsapp.received`](/docs/guides/whatsapp/webhooks/lifecycle#incoming-messages)                   | Un contacto te envía un mensaje                              |
| [`whatsapp.reacted`](/docs/guides/whatsapp/webhooks/reactions)                                      | Un contacto agrega, cambia o elimina una reacción            |
| [`whatsapp_suppression.created`](/docs/guides/whatsapp/webhooks/suppressions)                       | Se abre una supresión en tu espacio de trabajo               |
| [`whatsapp.group.join_request_created`](/docs/guides/whatsapp/webhooks/groups#join-request-created) | Alguien solicita unirse a un grupo                           |
| [`whatsapp.group.join_request_revoked`](/docs/guides/whatsapp/webhooks/groups#join-request-revoked) | Alguien cancela su solicitud para unirse a un grupo          |

La lista de tipos de evento es abierta: se pueden agregar nuevos tipos con el tiempo, así que trata un valor no reconocido como un evento futuro en lugar de un error.

## La estructura del evento

Cada evento de WhatsApp usa la [estructura estándar de webhook](/docs/guides/webhooks): un `type`, un `timestamp` y un objeto `data` específico del tipo.

```json
{
  "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"
}
```

## Campos que incluye todo evento de mensaje

Cada payload de webhook de WhatsApp para un mensaje incluye `whatsapp_id`, `workspace_id`, `direction`, `from`, `to`, `tags` y `metadata`. Los eventos de reacción, supresión y grupo no se refieren a un mensaje, por lo que cada uno tiene su propia estructura, descrita en su página.

- **Direcciones**: `from` y `to` pueden incluir un `phone_number` E.164, un [ID de usuario con alcance de negocio](/docs/guides/whatsapp/business-scoped-user-ids) de Meta en `bsuid`, o ambos. Un mensaje recibido de un usuario de WhatsApp también incluye el perfil que publica, en `username` y `display_name`.
- **`tags` y `metadata`** son `null` cuando el envío no incluyó ninguno.
- **`in_reply_to_message_id`** aparece en cada evento saliente de un mensaje enviado como respuesta, desde `whatsapp.accepted` hasta `whatsapp.read`, `whatsapp.failed` o `whatsapp.rejected`, indicando el mensaje que responde.

Los payloads de evento no incluyen el costo. Consulta el mensaje con [`GET /v1/whatsapp/messages/{message_id}`](/docs/api/reference/get-whatsapp-message) para ver cuánto costó.

## Próximos pasos

- [Webhooks de ciclo de vida de mensajes](/docs/guides/whatsapp/webhooks/lifecycle): payloads de entrega y mensajes entrantes
- [Eventos de ciclo de vida](/docs/guides/whatsapp/events/lifecycle): consulta la misma línea de tiempo a través de la API
- [Guía de webhooks](/docs/guides/webhooks): endpoints, firmas, reintentos y el catálogo completo de eventos

## 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)