Recibir mensajes de texto de WhatsApp
Un contacto que escribe en el chat produce un mensaje entrante con text. Es el brazo entrante más común y el que abre o reinicia la ventana de servicio al cliente.
Qué contiene un texto entrante
text.body contiene lo que el contacto escribió, y nada más acompaña al brazo:
Ejemplo de código
{
"id": "wam_01kya19eknftrs2s6p82asmvnh",
"direction": "inbound",
"from": { "phone_number": "+14155550100", "display_name": "Alex Rivera" },
"to": { "phone_number": "+13124495569" },
"status": "received",
"text": { "body": "Is my order out for delivery yet?" },
"created_at": "2026-08-25T09:04:11Z"
}preview_url es un campo del lado de envío. Un texto entrante no incluye ninguna marca de vista previa de enlace, sin importar lo que el cliente del contacto haya renderizado, así que una URL en body se lee como parte del texto.
El esquema de lectura no declara un máximo para un body entrante. El límite de 4096 caracteres pertenece al lado de envío, así que dimensiona tu almacenamiento como texto sin límite en lugar de ajustarlo a un tope que el brazo entrante no garantiza.
Un texto enviado como respuesta citada
Cuando el contacto responde a uno de tus mensajes citándolo, el brazo no cambia y in_reply_to_message_id indica el mensaje que respondió:
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",
"text": { "body": "Yes, that one" },
"created_at": "2026-08-25T09:06:02Z"
}WhatsApp no marca todas las respuestas, y una sin marcar no incluye ningún ID. Consulta respuestas citadas en el hub para saber qué puede omitir la resolución y cómo correlacionar sin ella.
El payload del webhook
whatsapp.received incluye el mismo brazo en el sobre del evento, así que un endpoint actúa sobre el texto sin necesidad de releer el mensaje:
Ejemplo de código
{
"type": "whatsapp.received",
"timestamp": "2026-08-25T09:04:11.118Z",
"data": {
"whatsapp_id": "wam_01kya19eknftrs2s6p82asmvnh",
"workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
"direction": "inbound",
"from": { "phone_number": "+14155550100", "display_name": "Alex Rivera" },
"to": { "phone_number": "+13124495569" },
"text": { "body": "Is my order out for delivery yet?" },
"tags": null,
"metadata": null
}
}Aspectos a tener en cuenta
- Un texto es la forma más económica en que un contacto reabre la ventana. Cualquier mensaje entrante reinicia la ventana de servicio a 24 horas, y un texto es lo que la mayoría de los contactos envía; una respuesta libre de tu parte es entregable desde ese momento.
- from puede llegar sin número de teléfono. Un contacto que ha adoptado un nombre de usuario de WhatsApp te contacta mediante ID de usuario con alcance de negocio, así que lee la identidad de from en lugar de asumir que from.phone_number está presente.
- El cuerpo es lo que el contacto escribió. Un toque en algo que enviaste llega como una respuesta interactiva en su propio brazo.
Siguientes pasos
- Cómo funciona la recepción: el sobre entrante, la obtención de medios y el webhook whatsapp.received
- Mensajes de texto plano de WhatsApp: el lado de envío del mismo brazo
- Recibir respuestas interactivas: cómo llega un toque en un botón o en una fila de lista
- Enviar mensajes de WhatsApp: responder dentro de la ventana de servicio y citar un mensaje
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