Recibir respuestas interactivas de WhatsApp
Una pulsación en un botón de respuesta, una fila de lista o un botón de respuesta rápida de plantilla llega como su propio mensaje entrante con interactive_reply. La rama te devuelve el identificador que asignaste en el envío, de modo que un flujo se ramifica según tu propio identificador y no según la etiqueta que vio el contacto.
Qué contiene una respuesta interactiva entrante
type indica el tipo de pulsación, y el campo con el mismo nombre la contiene:
Ejemplo de código
{
"id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
"direction": "inbound",
"from": { "phone_number": "+14155550100" },
"to": { "phone_number": "+13124495569" },
"status": "received",
"in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
"interactive_reply": {
"type": "button",
"button": { "slug": "cancel-booking", "text": "Cancel" }
},
"created_at": "2026-08-25T09:04:11Z"
}| type | Campo | Qué contiene |
|---|---|---|
| button | button | El slug y el text de un botón de respuesta o de un botón de respuesta rápida de plantilla |
| list | list | El slug y el text de la fila que eligió el contacto, más su description cuando tenía una |
Una fila de lista reemplaza button por list y añade la segunda línea que mostraba la fila:
Ejemplo de código
{
"interactive_reply": {
"type": "list",
"list": {
"slug": "priority_express",
"text": "Priority Mail Express",
"description": "Next day to 2 days"
}
}
}slug es el identificador que declaraste y que el contacto nunca vio; text es la etiqueta que leyó. Ramifica según slug. Las etiquetas se reformulan y traducen, y en una pulsación de un botón de respuesta rápida de plantilla, el slug es el payload que declaró esa plantilla, que WhatsApp establece como la propia etiqueta del botón.
La lista de tipos es abierta: WhatsApp añade tipos interactivos con el tiempo, así que trata un type que no reconozcas como un tipo futuro en vez de un error, y recurre a registrar el mensaje en lugar de fallar la lectura.
Vincular una pulsación con lo que enviaste
in_reply_to_message_id indica el mensaje que contenía el botón o el menú, y así sabes a qué pregunta pertenece esta respuesta. WhatsApp no lo reporta en cada pulsación, y la resolución también puede fallar; en ese caso el campo se omite en lugar de reportarse vacío. La sección de respuestas citadas del hub explica qué significa un fallo y cuánto tiempo un mensaje citado sigue siendo resoluble.
Cuando la correlación deba ser fiable, incluye tu propia referencia en el slug mismo o en metadata del envío, en lugar de depender del campo. Consulta citar un mensaje para el lado del envío.
Las dos pulsaciones que llegan por otra vía
Dos tipos interactivos responden sin un interactive_reply en absoluto:
- Una solicitud de ubicación vuelve como una ubicación entrante normal.
- Una solicitud de información de contacto vuelve como tarjetas de contacto, con origin establecido en contact_request.
Un botón de enlace no devuelve nada: el contacto sale hacia la URL y ningún mensaje entrante registra la pulsación. Una integración que solo observe interactive_reply se pierde las tres.
El payload del webhook
whatsapp.received incluye la rama interactive_reply en el sobre del evento, de modo que un bot puede responder a una pulsación sin volver a leer el mensaje:
Ejemplo de código
{
"type": "whatsapp.received",
"timestamp": "2026-08-25T09:04:11.118Z",
"data": {
"whatsapp_id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
"workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
"direction": "inbound",
"from": { "phone_number": "+14155550100", "display_name": "Alex Rivera" },
"to": { "phone_number": "+13124495569" },
"in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
"interactive_reply": {
"type": "button",
"button": { "slug": "cancel-booking", "text": "Cancel" }
},
"tags": null,
"metadata": null
}
}Puntos a tener en cuenta
- interactive y interactive_reply son direcciones opuestas. interactive es lo que enviaste y nunca llega como entrante; interactive_reply es lo que el contacto pulsó y nunca aparece en un mensaje saliente.
- Una pulsación reinicia la ventana de servicio. Es un mensaje entrante, así que reabre 24 horas de respuestas libres del mismo modo que un texto.
- Un contacto puede pulsar el mismo botón dos veces. Nada deduplica las pulsaciones, así que cada una es su propio mensaje con su propio ID. Haz que la acción que ejecutas ante un slug sea idempotente.
- Una pulsación en un menú antiguo sigue llegando. Un contacto que se desplace hacia atrás puede pulsar un botón de hace días, así que valida que el flujo siga abierto en lugar de asumir que la pulsación responde a tu último mensaje.
Siguientes pasos
- Cómo funciona la recepción: el sobre entrante, la obtención de medios y el webhook whatsapp.received
- Mensajes interactivos de WhatsApp: los seis tipos que un destinatario puede pulsar
- Botones de respuesta de WhatsApp: el lado del envío de una pulsación de botón
- Menús de lista de WhatsApp: el lado del envío de la elección de una fila
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