# Location Request Messages

> Ask a WhatsApp contact to share their location with a single tap. Useful for delivery addresses, field service dispatch and on-site check-ins.

Send a message with a **Send location** button. When the contact taps it, WhatsApp opens the location picker and their answer arrives back in the conversation as a regular inbound `location` message.

Use this instead of asking for an address in free text: you get exact coordinates rather than a string you have to geocode and correct.

## Send a Location Request

The prompt goes in `text`. There is no `content` object — WhatsApp owns the button, so there is nothing to configure.

```typescript
const message = await zavu.messages.send({
  to: "+14155551234",
  channel: "whatsapp",
  messageType: "location_request",
  text: "To finish your order, share the delivery address."
});
```

```bash
curl -X POST https://api.zavu.dev/v1/messages \
  -H "Authorization: Bearer zv_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155551234",
    "channel": "whatsapp",
    "messageType": "location_request",
    "text": "To finish your order, share the delivery address."
  }'
```

## Receiving the Answer

The reply is **not** a new message type. It arrives as a standard `message.inbound` webhook with `messageType: "location"`, and `content.replyToMessageId` set to the ID of the request you sent. That is how you correlate the two.

```json
{
  "type": "message.inbound",
  "data": {
    "messageId": "jd7x2k3m4n5p6q7r8s9t0",
    "from": "+14155551234",
    "channel": "whatsapp",
    "messageType": "location",
    "content": {
      "latitude": -33.4489,
      "longitude": -70.6693,
      "name": "Casa",
      "address": "Av. Providencia 1234, Santiago",
      "replyToMessageId": "jd6a1b2c3d4e5f6g7h8i9",
      "replyToMessageType": "location_request"
    }
  }
}
```

> **Warning:**
> `name` and `address` are optional — the contact only sends them if they pick a saved place instead of dropping a pin. Always read `latitude` and `longitude`; treat the other two as a bonus.

Store the ID returned when you send the request, then match it against `content.replyToMessageId` on the inbound event:

```typescript
if (
  event.type === "message.inbound" &&
  event.data.messageType === "location" &&
  event.data.content?.replyToMessageId === pendingRequestId
) {
  const { latitude, longitude } = event.data.content;
  await saveDeliveryCoordinates(orderId, latitude, longitude);
}
```

## Specifications

| Property | Requirement |
|----------|-------------|
| text | Required, max 1024 characters |
| content | Not used |
| channel | WhatsApp only |
| Button label | Fixed by WhatsApp, not customizable |

> **Note:**
> Like every non-template message, a location request needs an open [24-hour conversation window](https://www.zavu.dev/docs/guides/whatsapp/overview). Outside the window, open the conversation with a template first.

## Use Cases

- Confirming a delivery address before dispatch
- Sending a technician to a customer's site
- Finding the nearest branch or pickup point
- Roadside assistance and field service
- On-site check-ins