# WhatsApp location messages

A location message sends a pin: a point on the map, with an optional name and address underneath it. This is the send side; to ask a contact to share theirs instead, see [location requests](/docs/guides/whatsapp/message-types/interactive/location-requests).

## Send a location

Set `location.latitude` and `location.longitude`:

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

```typescript
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  location: { latitude: 37.7793, longitude: -122.4193 },
});
console.log(msg.id, msg.status);
```

```python
msg = client.whatsapp.send(
    to="+16505551234",
    from_="+13124495648",
    location={"latitude": 37.7793, "longitude": -122.4193},
)
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",
		Location: &bird.WhatsAppLocationSend{Latitude: 37.7793, Longitude: -122.4193},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}
```

```php
$location = (new WhatsAppMessageSendRequestLocation())
    ->setLatitude(37.7793)
    ->setLongitude(-122.4193);
$message = $bird->whatsapp->send(
    to: '+16505551234',
    from: '+13124495648',
    location: $location,
);
echo $message->getId(), ' ', $message->getStatus();
```

```cli
bird whatsapp send \
  --to +16505551234 \
  --from +13124495648 \
  --latitude 37.7793 \
  --longitude -122.4193
```

```curl
curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "to": "+16505551234",
      "from": "+13124495648",
      "location": {
        "latitude": 37.7793,
        "longitude": -122.4193
      }
    }'
```

<!-- /bird:tabs -->

The full shape adds `name` and `address`:

```json
{
  "to": "+16505551234",
  "from": "+13124495648",
  "location": {
    "latitude": 37.7793,
    "longitude": -122.4193,
    "name": "Ferry Building Pickup",
    "address": "1 Market St, San Francisco, CA 94105"
  }
}
```

`address` only displays to the recipient when `name` is also set. `from` is required on every service message: a number your workspace owns, not a Bird-managed one.

## Limits

| Field       | Bound                                                          | Enforced by             |
| ----------- | -------------------------------------------------------------- | ----------------------- |
| `latitude`  | required, -90 to 90, decimal degrees                           | Bird, at accept (`422`) |
| `longitude` | required, -180 to 180, decimal degrees                         | Bird, at accept (`422`) |
| `name`      | optional, up to 1000 characters                                | Bird, at accept (`422`) |
| `address`   | optional, up to 1000 characters, shown only when `name` is set | Bird, at accept (`422`) |

WhatsApp's own docs list `latitude` and `longitude` as required with no stated numeric range; the ±90/±180 range check and the 1000-character caps on `name` and `address` are Bird's own bounds.

## Reading an inbound location

A contact sharing their location, unprompted or in reply to a location request, produces an ordinary inbound `location` message. Nothing on it is guaranteed: a raw pin can arrive with no `name` and no `address` at all.

```json
{
  "id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
  "direction": "inbound",
  "from": { "phone_number": "+16505551234" },
  "to": { "phone_number": "+13124495648" },
  "location": {
    "latitude": 37.7793,
    "longitude": -122.4193,
    "name": "Ferry Building Pickup",
    "address": "1 Market St, San Francisco, CA 94105"
  },
  "status": "received"
}
```

An inbound location can also carry a `url` linking to the place, usually only on a business location; it never appears on a location you send. Location isn't a media type, so there's no file to fetch and no 30-day retention window. See [Receiving WhatsApp messages](/docs/guides/whatsapp/receiving-whatsapp) for the message list, the API, and the webhook path.

## Limits and edge cases

- **The customer service window has to be open.** A location send 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).
- **`name` and `address` are genuinely optional on read, not optional-with-a-fallback.** A raw pin has neither, and `address` never appears without `name`. Don't assume a street address accompanies a pair of coordinates.
- **This is not the same type as a location request.** [Location requests](/docs/guides/whatsapp/message-types/interactive/location-requests) are an interactive type that asks the recipient for their own location; this page sends one to them. Don't conflate the two send shapes.
- **A tap on a location request comes back as an ordinary inbound `location` message, not an `interactive_reply`.** An integration that watches only `interactive_reply` for taps misses this entirely; it has to also watch inbound `location`.

## Next steps

- [WhatsApp service messages](/docs/guides/whatsapp/message-types): the customer service window and the model every service message shares
- [Location requests](/docs/guides/whatsapp/message-types/interactive/location-requests): ask a contact for their location instead of sending one
- [How sending works](/docs/guides/whatsapp/sending-whatsapp): the request envelope, the `202` model, and safe retries