> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zavu.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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

  ```python Python theme={null}
  message = zavu.messages.send(
      to="+14155551234",
      channel="whatsapp",
      message_type="location_request",
      text="To finish your order, share the delivery address."
  )
  ```

  ```ruby Ruby theme={null}
  message = client.messages.send(
    to: "+14155551234",
    channel: "whatsapp",
    message_type: "location_request",
    text: "To finish your order, share the delivery address."
  )
  ```

  ```go Go theme={null}
  message, err := client.Messages.Send(context.TODO(), zavudev.MessageSendParams{
      To:          zavudev.String("+14155551234"),
      Channel:     zavudev.String("whatsapp"),
      MessageType: zavudev.String("location_request"),
      Text:        zavudev.String("To finish your order, share the delivery address."),
  })
  ```

  ```php PHP theme={null}
  $message = $client->messages->send([
      'to' => '+14155551234',
      'channel' => 'whatsapp',
      'messageType' => 'location_request',
      'text' => 'To finish your order, share the delivery address.',
  ]);
  ```

  ```bash cURL theme={null}
  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."
    }'
  ```
</CodeGroup>

## 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 theme={null}
{
  "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.
</Warning>

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

```typescript theme={null}
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](/guides/whatsapp/overview). Outside the window, open the conversation with a template first.
</Note>

## 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