Recibir ubicaciones de WhatsApp
Un pin que un contacto comparte llega como mensaje entrante con location. El mismo brazo responde a una solicitud de ubicación que enviaste, que es el único tipo interactivo cuya respuesta llega aquí en lugar de a interactive_reply.
Qué contiene una ubicación entrante
Ejemplo de código
{
"id": "wam_01kyf8u2shzx0v6m9q3bag8tje",
"direction": "inbound",
"from": { "phone_number": "+14155550100" },
"to": { "phone_number": "+13124495569" },
"status": "received",
"in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
"location": {
"latitude": 37.7793,
"longitude": -122.4193,
"name": "Embarcadero Plaza",
"address": "1 Market St, San Francisco, CA 94105"
},
"created_at": "2026-08-25T09:23:14Z"
}| Campo | Qué contiene |
|---|---|
| latitude | Latitud en grados decimales |
| longitude | Longitud en grados decimales |
| name | El nombre del lugar; ausente cuando el contacto compartió un pin simple |
| address | La dirección postal, que WhatsApp envía solo junto con un name |
| url | Un enlace al lugar, principalmente en una ubicación de negocio, cuando el cliente del remitente lo proporcionó |
Un pin simple colocado en el mapa solo lleva las dos coordenadas, así que trata name, address y url como decoración que muestras cuando está presente en lugar de campos clave. Lee las coordenadas como números JSON y espera valores negativos en los hemisferios sur y oeste.
Una ubicación que responde a una solicitud de ubicación
Cuando el pin responde a una solicitud de ubicación que enviaste, WhatsApp reporta la petición como el destino de la respuesta y in_reply_to_message_id indica el mensaje que contenía el botón. Eso es lo que vincula una respuesta con una pregunta, y es la diferencia con una solicitud de información de contacto, cuya respuesta no incluye ese vínculo.
Nada más marca el pin como respuesta. Un contacto que comparte su ubicación sin que se la pidas produce el mismo brazo sin in_reply_to_message_id, así que una integración que espera una respuesta verifica ese campo en lugar del brazo. El campo tampoco es una garantía en la dirección contraria: WhatsApp no marca todas las respuestas y la resolución puede fallar, así que una respuesta genuina puede llegar sin él. La sección de respuestas citadas del hub cubre cuándo ocurre eso y qué hacer cuando la clasificación debe mantenerse.
El payload del webhook
whatsapp.received lleva el brazo location en el sobre del evento:
Ejemplo de código
{
"type": "whatsapp.received",
"timestamp": "2026-08-25T09:23:14.507Z",
"data": {
"whatsapp_id": "wam_01kyf8u2shzx0v6m9q3bag8tje",
"workspace_id": "ws_01ky7m235keycbnwyajabe1a6b",
"direction": "inbound",
"from": { "phone_number": "+14155550100" },
"to": { "phone_number": "+13124495569" },
"in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
"location": {
"latitude": 37.7793,
"longitude": -122.4193,
"name": "Embarcadero Plaza",
"address": "1 Market St, San Francisco, CA 94105"
},
"tags": null,
"metadata": null
}
}Aspectos a tener en cuenta
- La ubicación en tiempo real compartida no se modela como contenido. Lo que llega es una ubicación fija en un momento, así que una vista de seguimiento no tiene nada que actualizar. No construyas una sobre este campo.
- Una integración que solo observa interactive_reply no capta esto. La respuesta a una solicitud de ubicación llega aquí, y la respuesta a una solicitud de información de contacto llega en contact_cards, así que un handler que solo lee taps pierde ambas.
- Las coordenadas son lo que reportó el dispositivo del contacto. No incluyen radio de precisión ni altitud, y un pin que el contacto arrastró está donde lo arrastró. Confirma la dirección con palabras cuando tenga que ser correcta.
Próximos pasos
- Cómo funciona la recepción: el sobre entrante, la obtención de medios y el webhook whatsapp.received
- Mensajes de ubicación de WhatsApp: el lado de envío del mismo brazo
- Solicitudes de ubicación de WhatsApp: el botón que pide un pin
- Eventos de WhatsApp: la lista completa de eventos, a través de API o webhooks
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