# Receiving WhatsApp locations

A pin a contact shares arrives as an inbound message carrying `location`. The same arm answers a [location request](/docs/guides/whatsapp/message-types/interactive/location-requests) you sent, which is the only interactive type whose reply lands here rather than on `interactive_reply`.

## What an inbound location carries

```json
{
  "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"
}
```

| Field       | What it carries                                                                           |
| ----------- | ----------------------------------------------------------------------------------------- |
| `latitude`  | Latitude in decimal degrees                                                               |
| `longitude` | Longitude in decimal degrees                                                              |
| `name`      | The name of the place; absent when the contact shared a plain pin                         |
| `address`   | The street address, which WhatsApp sends only alongside a `name`                          |
| `url`       | A link to the place, mainly on a business location, when the sender's client supplied one |

A plain pin dropped on the map carries the two coordinates and nothing else, so treat `name`, `address`, and `url` as decoration you display when present rather than fields to key on. Read the coordinates as JSON numbers, and expect negative values in the southern and western hemispheres.

## A location that answers a location request

When the pin answers a location request you sent, WhatsApp reports the ask as the reply's target and `in_reply_to_message_id` names the message that carried the button. That is what ties an answer to a question, and it is the distinction with a [contact info request](/docs/guides/whatsapp/message-types/interactive/contact-info-requests), whose reply carries no such link.

Nothing else marks the pin as an answer. A contact who shares their location unprompted produces the same arm with no `in_reply_to_message_id`, so an integration watching for an answer checks that field rather than the arm. The field is not a guarantee in the other direction: WhatsApp does not mark every reply, and resolution can miss, so a genuine answer can arrive without it. The hub's [quoted replies](/docs/guides/whatsapp/receiving-whatsapp#quoted-replies) covers when that happens and what to do where the classification has to hold.

## The webhook payload

`whatsapp.received` carries the `location` arm on the event envelope:

```json
{
  "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
  }
}
```

## Things to watch

- **Live location sharing is not modelled as content.** What arrives is one location fixed at one moment, so a tracking view has nothing to update from. Do not build one on this field.
- **An integration watching only `interactive_reply` misses this.** A location request's answer arrives here, and a contact info request's answer arrives on `contact_cards`, so a handler that reads taps alone drops both.
- **Coordinates are what the contact's device reported.** They carry no accuracy radius and no altitude, and a pin the contact dragged is wherever they dragged it. Confirm an address in words when it has to be right.

## Next steps

- [How receiving works](/docs/guides/whatsapp/receiving-whatsapp): the inbound envelope, media fetching, and the `whatsapp.received` webhook
- [WhatsApp location messages](/docs/guides/whatsapp/message-types/location): the send side of the same arm
- [WhatsApp location requests](/docs/guides/whatsapp/message-types/interactive/location-requests): the button that asks for a pin
- [WhatsApp events](/docs/guides/whatsapp/events): the full event list, over the API or webhooks