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

# Ask for a WhatsApp location or delivery address

> Use WhatsApp interactive messages to collect a customer's location or delivery address inside the 24-hour customer-service window.

# Ask for a location or delivery address in WhatsApp

Use Orbit's WhatsApp interactive messages when your next step needs a customer's current location or a delivery address. The customer can share the information without leaving the conversation, and the reply arrives in the same conversation thread.

Before you begin, connect a WhatsApp Business Account and make sure the customer has messaged your business within the last 24 hours. These messages are free-form interactive messages, so they do not need a template submission or review.

## 1. Choose an endpoint

Orbit exposes both endpoints under `https://api.orbit.devotel.io/api/v1/whatsapp` and authenticates them with your `X-API-Key` header.

### Request the customer's location

Call `POST /messages/send-location-request` with a short prompt. Orbit sends Meta an interactive `location_request_message`, and WhatsApp displays a **Send location** button. When the customer accepts, Meta sends a plain `location` inbound message containing coordinates.

### Request a delivery address

Call `POST /messages/send-address-request` with the customer's market in `country`. WhatsApp displays its structured address form for that market. The completed form arrives as an `interactive` inbound message with `type: "address_message"`.

Both routes are owner-admin sends and are limited to WhatsApp. They are not interchangeable with SMS or another messaging channel.

## 2. Request bodies and validation

Both requests require `to` and `body`:

| Field | Type | Rules |
| - | - | - |
| `to` | string | Required and non-empty. Use the recipient's E.164 phone number or WhatsApp Business Solution UID. |
| `body` | string | Required, non-empty, and 1–1024 characters. This is the prompt shown above the control. |

The location request has no other fields:

```json theme={null}
{
  "to": "+14155552671",
  "body": "Please share your location so we can find your nearest pickup point."
}
```

The address request adds these fields:

| Field | Type | Rules |
| - | - | - |
| `country` | string | Required, exactly two characters. Use an ISO 3166-1 alpha-2 code such as `IN` or `SG`; it selects the address fields WhatsApp renders. |
| `values` | object | Optional. String values keyed by the market-specific field names; use it to pre-fill known values. |
| `saved_addresses` | array | Optional. An array of address objects the customer can choose from in markets that support saved addresses. |

Example with a pre-filled delivery form:

```json theme={null}
{
  "to": "+14155552671",
  "body": "Where should we deliver your order?",
  "country": "IN",
  "values": {
    "name": "Asha Rao"
  },
  "saved_addresses": [
    {
      "name": "Home",
      "address": "12 MG Road",
      "city": "Bengaluru",
      "in_pin_code": "560001",
      "country": "IN"
    }
  ]
}
```

Do not add a template name or template components to either request. These interactive prompts are intended for an open 24-hour customer-service window.

## 3. Read the reply in your webhook

Subscribe to `message.received` and use the inbound payload to update the same conversation. Orbit threads both reply types into the conversation inbox; see [add a topic to the inbox](/guides/inbox-add-topic) for inbox routing and topic handling.

### Location reply

A location reply is a plain `location` message, not an `interactive` reply. Read `latitude` and `longitude` from `message.location`:

```json theme={null}
{
  "type": "location",
  "location": {
    "latitude": 12.9716,
    "longitude": 77.5946,
    "name": "Pickup point",
    "address": "MG Road, Bengaluru"
  }
}
```

Use the coordinates only for the action the customer requested, such as finding a nearby store or confirming a pickup point.

### Delivery-address reply

An address reply is an interactive message with `type: "address_message"`. Meta's exact field names depend on `country`. Your integration should accept the fields returned for that market. A normalized example looks like this:

```json theme={null}
{
  "type": "interactive",
  "interactive": {
    "type": "address_message",
    "address_message": {
      "street": "12 MG Road",
      "city": "Bengaluru",
      "postcode": "560001",
      "country": "IN"
    }
  }
}
```

Some markets return names such as `address`, `in_pin_code`, `building_name`, `landmark_area`, `state`, or `zip_code` instead of `street` and `postcode`. Preserve the returned field names when you store or forward the address. Do not assume every market returns the same set.

## 4. Use customer data only for the requested action

Ask for a location or delivery address only when you expect to use it for that conversation, such as locating a pickup point or fulfilling an order. Explain why you need it, collect only the fields required for that purpose, and apply your tenant's retention and deletion controls. Do not save, enrich, profile, or mine location and address data for unrelated purposes.

## 5. Try each request with curl

Replace the API key and recipient with your values. Run these calls while the customer's 24-hour window is open.

### Location request

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/whatsapp/messages/send-location-request \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "body": "Please share your location so we can find your nearest pickup point."
  }'
```

After the customer taps **Send location**, your `message.received` consumer receives the `location` payload shown above.

### Delivery-address request

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/whatsapp/messages/send-address-request \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+14155552671",
    "body": "Where should we deliver your order?",
    "country": "IN"
  }'
```

After the customer submits the form, your `message.received` consumer receives an `address_message` payload with the returned street, city, postcode, country, and any other market-specific fields, as shown above.

## 6. Handle denials and unsupported channels

* **Customer declines or dismisses the control:** treat the reply as absent. Do not repeatedly ask. Offer a clear alternative, such as asking the customer to type the information or contact support.
* **The customer sends a different WhatsApp reply:** keep the conversation open and ask a focused follow-up rather than assuming that the location or address was shared.
* **The destination is SMS:** SMS cannot render WhatsApp location-request buttons or address forms. Detect the channel before sending and use a plain-text fallback that asks the customer to reply with the required address or a map link. Do not send a WhatsApp interactive payload through an SMS route.
* **The 24-hour window is closed:** the API rejects the free-form interactive send. Use an approved WhatsApp template to ask the customer to reply, then send the location or address request after the window reopens. See [WhatsApp's 24-hour freeform window](/guides/whatsapp/24h-window).

## See also

* [Get started with WhatsApp](/guides/whatsapp/getting-started)
* [WhatsApp's 24-hour freeform window](/guides/whatsapp/24h-window)
* [WhatsApp Flows](/guides/whatsapp/whatsapp-flows) for multi-screen forms


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.