Documentation
Sign inGet started
Aan de slag
Gidsen
API Reference
SDK's
CLI
Kennisbank
Changelog

WhatsApp location requests

A location request puts one button under a WhatsApp message that asks the recipient to share where they are. Use it when you need a current position, such as a pickup point, rather than a saved address. For a phone number instead, use contact info requests.

Send a location request

Set interactive.type to location_request_message, with a body_text and nothing else. WhatsApp renders the button itself, so there is nothing to label it with:
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 is required on every service message: a number your workspace owns, not a Bird-managed one. This type names no field of its own, and the schema bars a header, a footer_text, and every other type's field (buttons, list, cta_url, cards) outright, so body_text is the whole message, capped at 1024 characters.
in_reply_to_message_id still works on this type, to quote an earlier message in the same conversation. See the hub's quoting a message to correlate a reply for how resolution works and what it can miss.

Reading the shared location

A tap does not produce an interactive_reply. It arrives as an ordinary inbound location message, the same shape a contact sharing their location unprompted would produce, so an integration that already reads inbound locations needs no new branch for this type:
Codevoorbeeld
{
  "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"
}
None of location's fields are required: latitude and longitude are usually both present, but name is absent when the recipient shared a plain pin, address only appears when name is also set, and url appears only on business locations the recipient's client happened to supply. Code defensively rather than assuming a street address comes with the pin. You see this reply through the message list or GET /v1/whatsapp/messages/{id}; see the hub's reading a reply for that path in full.

Correlating the answer with the question

Meta sets a context on this type's reply naming the request it answers, so the inbound message carries in_reply_to_message_id and you need no correlation scheme of your own:
Codevoorbeeld
{
  "direction": "inbound",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "location": { "latitude": 37.7793, "longitude": -122.4193 }
}
See quoting a message to correlate a reply for how that resolution works and what a miss looks like.
This is the deliberate contrast with contact info requests: that type's reply carries no context at all, so its in_reply_to_message_id never resolves and correlation falls back to from plus timing. A location request's reply does resolve, so in_reply_to_message_id is the reliable way to tie the shared location back to the request that asked for it.

Things to watch

  • The customer service window has to be open. A location request is a service message, deliverable only inside an open window; see the hub's customer service window. The window check fails open, so a 202 is not proof the window was actually open when the send goes out.
  • from must be a number your workspace owns. Omitting it, or naming a number that isn't a connected sender, is rejected before the send is created.
  • No reply is guaranteed. The recipient can dismiss the location-sharing screen, ignore the message entirely, or type an address as free text instead, which arrives as an ordinary inbound text message with no location at all. Meta documents no signal for a declined or dismissed share, so treat the ask as fire-and-forget and time out on your own side rather than waiting on a response that may never come.
  • A shared pin can carry coordinates only. The recipient's client decides whether to attach a name and address; a plain pin has neither, so do not assume one comes with the other.
  • No header, no footer, and no field of its own. The schema bars a header and footer_text on this type outright, and there is no field to label the button with. Any small print you need has to go inside body_text.
  • The reply is a location message, not an interactive_reply. An integration that only watches interactive_reply for a tap will miss this type entirely; watch inbound location instead.
Everything the schema can express here, an over-long body_text, a header, a footer_text, or any of buttons, list, cta_url, cards, is a plain request-validation failure with no catalog code. The one interactive-specific pair that can fire on this type is E15057 and E15058, both on in_reply_to_message_id when a quote doesn't resolve or can't be quoted; see the hub's errors for the full interactive error table and How sending works for the errors any WhatsApp send can hit.

Next steps