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.

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.

{
  "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 estado de mensaje: payloads de entrega y fallo
• Webhooks de mensaje entrante: el payload de whatsapp.received
• Webhooks de reacciones: el payload de whatsapp.reacted
• Guía de webhooks: endpoints, firmas, reintentos y el catálogo completo de eventos