Recibir reacciones de WhatsApp

Suscríbete a los cambios de reacciones para saber cuándo un contacto añade un emoji a uno de tus mensajes, lo cambia o lo retira. Las reacciones anotan un mensaje existente y llegan a través de whatsapp.reacted.

Requisitos previos

Configura un endpoint de webhook para tu espacio de trabajo. Para consultar las reacciones actuales o su historial, usa una clave API con permiso de lectura de WhatsApp.

1. Suscríbete a los cambios de reacciones

Añade whatsapp.reacted a tu suscripción de webhook. Una suscripción a whatsapp.received no incluye reacciones. Sigue la guía de webhooks para la verificación de firma, los reintentos de entrega y la configuración de endpoints.

Las reacciones no crean un mensaje nuevo en la lista de mensajes ni abren una ventana de atención al cliente. Si necesitas responder, consulta las reglas de ventana de servicio antes de enviar un mensaje de formato libre.

2. Identifica el mensaje y el cambio

Lee el data.whatsapp_id del evento para encontrar el mensaje al que reaccionó el contacto. Es el ID de mensaje Bird original (wam_…), no un ID de reacción separado.

Usa data.from para identificar al contacto y data.to para identificar tu remitente WhatsApp. Son objetos de dirección WhatsApp; gestiona los identificadores de usuario con alcance de negocio cuando la dirección del contacto no tiene número de teléfono.

Un contacto que añade una reacción de pulgar arriba produce este webhook:

Ejemplo de código

{
  "data": {
    "emoji": "👍",
    "from": { "phone_number": "+14155550100" },
    "to": { "phone_number": "+13124495569" },
    "whatsapp_id": "wam_01ky8b3xq4gd7pmzn2ka51f7te",
    "workspace_id": "ws_01ky7m235keycbnwyajabe1a6b"
  },
  "timestamp": "2026-08-28T19:01:10.000Z",
  "type": "whatsapp.reacted"
}

Interpreta data.emoji de la siguiente manera:

Un emoji no nulo añade o reemplaza la reacción de ese contacto en el mensaje referenciado.
Un emoji null elimina la reacción de ese contacto. El campo está presente en un evento de eliminación.

Un reemplazo llega como un solo evento con el emoji nuevo; no hay un evento de eliminación separado para el emoji anterior. Conserva la cadena exacta: ❤ y ❤️ son valores distintos en el payload.

3. Consulta las reacciones actuales

Si tu aplicación muestra la reacción actualmente asociada a un mensaje, consulta el mensaje y lee su reactions. La lista contiene una reacción vigente por remitente y se omite cuando no hay reacciones vigentes.

Para GET /v1/whatsapp/messages/wam_01ky8b3xq4gd7pmzn2ka51f7te, los campos relacionados con reacciones tienen esta forma (otros campos del mensaje omitidos):

Ejemplo de código

{
  "id": "wam_01ky8b3xq4gd7pmzn2ka51f7te",
  "reactions": [
    {
      "emoji": "👍",
      "from": { "phone_number": "+14155550100" }
    }
  ]
}

El mensaje conserva su contenido, dirección y estado de entrega originales. reactions[].from identifica a la persona que reaccionó.

No trates el último webhook que recibes como el estado actual. WhatsApp reporta los tiempos de reacción con precisión de segundo, por lo que varios cambios pueden compartir marca de tiempo, y los reintentos de webhook pueden alterar el orden de llegada. Usa los webhooks para disparar una actualización de las reacciones actuales del mensaje.

4. Inspecciona el historial de reacciones

Lista los eventos de reacción para inspeccionar los cambios en el mensaje referenciado. Los cambios entrantes de contactos tienen estado received; una eliminación lleva emoji: null. La lista también incluye los resultados de las reacciones que envió tu espacio de trabajo.

El API de eventos de reacción devuelve una respuesta paginada. Este ejemplo muestra una reacción de negocio rechazada y una reacción de contacto recibida anteriormente:

Ejemplo de código

{
  "data": [
    {
      "id": "war_01krdgeqcxet5s7t44vh8rt9mh",
      "emoji": "🎉",
      "status": "rejected",
      "from": {
        "phone_number": "+13124495569"
      },
      "error": {
        "code": "internal_error",
        "description": "the receiving number is no longer connected",
        "occurred_at": "2026-08-28T19:04:22Z"
      },
      "occurred_at": "2026-08-28T19:04:22Z"
    },
    {
      "id": "war_01krdgeqcxet5s7t44vh8rt9mg",
      "emoji": "👍",
      "status": "received",
      "from": {
        "phone_number": "+14155550100",
        "bsuid": "US.13491208655302741918"
      },
      "occurred_at": "2026-08-28T19:01:10Z"
    }
  ],
  "next_cursor": null,
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiMjAyNi0wOC0yOFQxOTowNDoyMloiLCJpIjoiMDE5ZTFiMDctNWQ5ZC03NjhiLTkzZTgtODRkYzUxOGQyNjkxIn0"
}

El historial de reacciones es independiente de los eventos de entrega del mensaje. El endpoint de eventos del mensaje no contiene cambios de whatsapp.reacted. Para retención y paginación, sigue la referencia del registro de reacciones.

Solución de problemas

No llega el webhook de reacción: Verifica que la suscripción incluya whatsapp.reacted. Una reacción a un mensaje antiguo cuya referencia de proveedor ya no se puede resolver no produce reacción coincidente, entrada de registro ni webhook.
La reacción no aparece en la lista de mensajes: Busca el mensaje original. La reacción está asociada a él y no tiene una fila de mensaje separada.
El estado de la reacción cambia inesperadamente: Actualiza el reactions del mensaje original en lugar de ordenar los eventos de webhook por hora de llegada o marca de tiempo.

Próximos pasos

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