# 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](/docs/guides/whatsapp/message-types/interactive/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:

<!-- bird:tabs typescript,python,go,php,cli,curl -->

```typescript
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);
```

```python
msg = client.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.",
    },
)
print(msg.id, msg.status)
```

```go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
		To:   "+16505551234",
		From: "+13124495648",
		Interactive: &bird.WhatsAppInteractiveSend{
			Type:     "location_request_message",
			BodyText: "Let's start with your pickup. Share your current location, or type an address instead.",
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}
```

```php
$interactive = (new WhatsAppMessageSendRequestInteractive())
    ->setType('location_request_message')
    ->setBodyText("Let's start with your pickup. Share your current location, or type an address instead.");

$message = $bird->whatsapp->send(
    to: '+16505551234',
    from: '+13124495648',
    interactive: $interactive,
);
echo $message->getId(), ' ', $message->getStatus();
```

```cli
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."}'
```

```curl
curl -X POST "https://{region}.platform.bird.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "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."
    }
  }'
```

<!-- /bird:tabs -->

`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](/docs/guides/whatsapp/message-types/interactive#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:

```json
{
  "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](/docs/guides/whatsapp/message-types/interactive#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:

```json
{
  "direction": "inbound",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "location": { "latitude": 37.7793, "longitude": -122.4193 }
}
```

See [quoting a message to correlate a reply](/docs/guides/whatsapp/message-types/interactive#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](/docs/guides/whatsapp/message-types/interactive/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](/docs/guides/whatsapp/message-types#the-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](/docs/api/errors/E15057) and [E15058](/docs/api/errors/E15058), both on `in_reply_to_message_id` when a quote doesn't resolve or can't be quoted; see the hub's [errors](/docs/guides/whatsapp/message-types/interactive#errors) for the full interactive error table and [How sending works](/docs/guides/whatsapp/sending-whatsapp) for the errors any WhatsApp send can hit.

## Next steps

- [WhatsApp interactive messages](/docs/guides/whatsapp/message-types/interactive): what all six interactive types share
- [Contact info requests](/docs/guides/whatsapp/message-types/interactive/contact-info-requests): ask for a phone number instead of a location
- [How sending works](/docs/guides/whatsapp/sending-whatsapp): the request envelope, the `202` model, and safe retries