Sign inGet started

Solicitudes de ubicación de WhatsApp

Una solicitud de ubicación coloca un botón debajo de un mensaje de WhatsApp que pide al destinatario compartir dónde se encuentra. Úsala cuando necesitas una posición actual, como un punto de recogida, en lugar de una dirección guardada. Si necesitas un número de teléfono, usa las solicitudes de información de contacto.

Enviar una solicitud de ubicación

Establece interactive.type en location_request_message, con un body_text y nada más. WhatsApp renderiza el botón en sí, así que no hay nada con qué etiquetarlo:
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  interactive: {
    type: "location_request_message",
    body_text:
      "Let's start with your pickup. Share your current location, or type an address instead.",
  },
});
console.log(msg.id, msg.status);
from es obligatorio en cada mensaje de servicio: un número que tu espacio de trabajo posee, no uno gestionado por Bird. Este tipo no nombra ningún campo propio, y el esquema prohíbe un header, un footer_text y todos los campos de los demás tipos (buttons, list, cta_url, cards) directamente, así que body_text es el mensaje completo, con un máximo de 1024 caracteres.
in_reply_to_message_id sigue funcionando en este tipo, para citar un mensaje anterior en la misma conversación. Consulta en el hub citar un mensaje para correlacionar una respuesta para saber cómo funciona la resolución y qué puede fallar.

Leer la ubicación compartida

Un toque no produce un interactive_reply. Llega como un mensaje entrante de location normal, con la misma forma que produciría un contacto compartiendo su ubicación sin que se la pidieras, así que una integración que ya lee ubicaciones entrantes no necesita una nueva rama para este tipo:
Ejemplo de código
{
  "id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
  "direction": "inbound",
  "from": { "phone_number": "+16505551234" },
  "to": { "phone_number": "+13124495648" },
  "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:04:11Z"
}
Ninguno de los campos de location es obligatorio: latitude y longitude suelen estar presentes ambos, pero name no aparece cuando el destinatario compartió un pin simple, address solo aparece cuando name también está establecido, y url aparece solo en ubicaciones de negocios que el cliente del destinatario incluyó. Programa de forma defensiva en lugar de asumir que una dirección postal acompaña al pin. Ves esta respuesta a través de la lista de mensajes o GET /v1/whatsapp/messages/{id}; consulta en el hub leer una respuesta para conocer esa ruta completa.

Correlacionar la respuesta con la pregunta

Meta establece un context en la respuesta de este tipo que nombra la solicitud que contesta, así que el mensaje entrante lleva in_reply_to_message_id y no necesitas un esquema de correlación propio:
Ejemplo de código
{
  "direction": "inbound",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "location": { "latitude": 37.7793, "longitude": -122.4193 }
}
Consulta citar un mensaje para correlacionar una respuesta para saber cómo funciona esa resolución y cómo se ve un fallo.
Este es el contraste deliberado con las solicitudes de información de contacto: la respuesta de ese tipo no lleva context en absoluto, así que su in_reply_to_message_id nunca resuelve y la correlación recurre a from más temporización. La respuesta de una solicitud de ubicación sí resuelve, así que in_reply_to_message_id es la forma fiable de vincular la ubicación compartida con la solicitud que la pidió.

Aspectos a tener en cuenta

  • La ventana de servicio al cliente tiene que estar abierta. Una solicitud de ubicación es un mensaje de servicio, entregable solo dentro de una ventana abierta; consulta en el hub la ventana de servicio al cliente. La comprobación de la ventana falla en abierto, así que un 202 no es prueba de que la ventana estuviera realmente abierta cuando se realiza el envío.
  • from debe ser un número que tu espacio de trabajo posee. Omitirlo, o nombrar un número que no sea un remitente conectado, se rechaza antes de que se cree el envío.
  • No se garantiza ninguna respuesta. El destinatario puede cerrar la pantalla de compartir ubicación, ignorar el mensaje por completo, o escribir una dirección como texto libre, que llega como un mensaje de texto entrante normal sin location en absoluto. Meta no documenta ninguna señal para una compartición rechazada o descartada, así que trata la solicitud como disparar y olvidar y gestiona un tiempo de espera en tu lado en lugar de esperar una respuesta que puede no llegar nunca.
  • Un pin compartido puede contener solo coordenadas. El cliente del destinatario decide si adjunta un nombre y una dirección; un pin simple no tiene ninguno de los dos, así que no asumas que uno viene con el otro.
  • Sin encabezado, sin pie de página y sin campo propio. El esquema prohíbe un header y un footer_text en este tipo directamente, y no hay campo para etiquetar el botón. Cualquier texto adicional que necesites tiene que ir dentro de body_text.
  • La respuesta es un mensaje location, no un interactive_reply. Una integración que solo observa interactive_reply para detectar un toque perderá este tipo por completo; observa mensajes entrantes location en su lugar.
Todo lo que el esquema puede expresar aquí, un body_text demasiado largo, un header, un footer_text, o cualquiera de buttons, list, cta_url, cards, es un simple fallo de validación de solicitud sin código de catálogo. Una cita que no resuelve falla la solicitud antes de que nada se cree o se cobre: 404 E15071 cuando el id no nombra ningún mensaje que este espacio de trabajo posea, 422 E15072 cuando nombra uno que no puede citarse. Consulta en el hub los errores para la tabla interactiva completa de errores y Enviar mensajes de WhatsApp para los errores que cualquier envío de WhatsApp puede encontrar.

Próximos pasos