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:

{
  "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:

{
  "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 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:

{
  "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:

{
  "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

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

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.

WhatsApp

Developer console

Guides

Messaging Controls

Audience & Support Tools

Ask for a WhatsApp location or delivery address

Ask for a location or delivery address in WhatsApp

1. Choose an endpoint

Request the customer’s location

Request a delivery address

2. Request bodies and validation

3. Read the reply in your webhook

Location reply

Delivery-address reply

4. Use customer data only for the requested action

5. Try each request with curl

Location request

Delivery-address request

6. Handle denials and unsupported channels

See also

​Ask for a location or delivery address in WhatsApp

​1. Choose an endpoint

​Request the customer’s location

​Request a delivery address

​2. Request bodies and validation

​3. Read the reply in your webhook

​Location reply

​Delivery-address reply

​4. Use customer data only for the requested action

​5. Try each request with curl

​Location request

​Delivery-address request

​6. Handle denials and unsupported channels

​See also

Ask for a location or delivery address in WhatsApp

1. Choose an endpoint

Request the customer’s location

Request a delivery address

2. Request bodies and validation

3. Read the reply in your webhook

Location reply

Delivery-address reply

4. Use customer data only for the requested action

5. Try each request with curl

Location request

Delivery-address request

6. Handle denials and unsupported channels

See also