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 o con POST /v1/webhooks. La guía de 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 | Bird acepta una solicitud de envío saliente |
| whatsapp.sent | Bird entrega el mensaje a la red de WhatsApp |
| whatsapp.delivered | WhatsApp confirma la entrega al dispositivo del destinatario |
| whatsapp.read | El destinatario abre el mensaje |
| whatsapp.failed | El mensaje no se puede entregar |
| whatsapp.rejected | Bird rechaza el mensaje antes de enviarlo |
| whatsapp.received | Un contacto te envía un mensaje |
| whatsapp.reacted | Un contacto agrega, cambia o elimina una reacción |
| whatsapp_suppression.created | Se abre una supresión en tu espacio de trabajo |
| whatsapp.group.join_request_created | Alguien solicita unirse a un grupo |
| whatsapp.group.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: un type, un timestamp y un objeto data específico del tipo.
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"
}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 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} para ver cuánto costó.
Próximos pasos
- Webhooks de ciclo de vida de mensajes: payloads de entrega y mensajes entrantes
- Eventos de ciclo de vida: consulta la misma línea de tiempo a través de la API
- Guía de webhooks: endpoints, firmas, reintentos y el catálogo completo de eventos
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