Location Request Messages

You can only send a interactive message up until 24 hours after receiving a message from the user. If you have not received a message from the user within this time, you will need to start a new conversation by sending a Template message.

Location request messages are free-form messages displaying only a body text and a send location button. When a WhatsApp user taps the button, a location sharing screen appears which the user can then use to share their location.

Once the user shares their location, a messages webhook is triggered, containing the user's location details to the business.

Sending Location Request Messages

POST https://waba-v2.360dialog.io/messages

To send a message, use the request URL and the following body parameters.

Request Body

Name	Type	Description
recipient_type	string	individual
to	string	wa_idof the contact you want to message
type	string	location_request_message
messaging_product	string	Required only for Cloud API. Messaging service used for the request. Use "whatsapp".
interactive	object

201: Created

A successful response includes a messages object with an ID for the newly created message.

{
    "messaging_product": "whatsapp",
    "contacts": [
        {
            "input": "16505076520",
            "wa_id": "16505076520"
        }
    ],
    "messages": [
        {
            "id": "wamid.HBgLMTY1MDUwNzY1MjAVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA"
        }
    ]
}

Post Body

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "type": "interactive",
  "to": "<WHATSAPP_USER_PHONE_NUMBER>",
  "interactive": {
    "type": "location_request_message",
    "body": {
      "text": "<BODY_TEXT>"
    },
    "action": {
      "name": "send_location"
    }
  }
}

Body Properties

Placeholder	Description	Example Value
<BODY_TEXT> String	Required. Message body text. Supports URLs. 4096 characters maximum.	Let's start with your pickup. You can either manually *enter an address* or *share your current location*.

Example Request

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "type": "interactive",
  "to": "[phone]",
  "interactive": {
    "type": "location_request_message",
    "body": {
      "text": "Let us start with your pickup. You can either manually *enter an address* or *share your current location*."
    },
    "action": {
      "name": "send_location"
    }
  }
}'

Example Response

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "[phone]",
      "wa_id": "15551234567"
    }
  ],
  "messages": [
    {
      "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBJCNUQ5RUNBNTk3OEQ2M0ZEQzgA"
    }
  ]

Webhook

When a WhatsApp user shares their location in response to your message, a messages webhook is triggered containing the user's location details. See Receiving messages via Webhook.

The location component within the payload contains the user's latitude and longitude. Note that address and name are optional for the user and may not be included.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "<WHATSAPP_BUSINESS_DISPLAY_PHONE_NUMBER>",
              "phone_number_id": "<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>"
            },
            "contacts": [
              {
                "profile": {
                  "name": "<WHATSAPP_USER_NAME>"
                },
                "wa_id": "<WHATSAPP_USER_ID>"
              }
            ],
            "messages": [
              {
                "context": {
                  "from": "<WHATSAPP_BUSINESS_PHONE_NUMBER>",
                  "id": "<WHATSAPP_CONTEXT_MESSAGE_ID>"
                },
                "from": "<WHATSAPP_USER_ID>",
                "id": "<WHATSAPP_MESSAGE_ID>",
                "timestamp": "<TIMESTAMP>",
                "location": {
                  "address": "<LOCATION_ADDRESS>", #Optional
                  "latitude": <LOCATION_LATITUDE>,
                  "longitude": <LOCATION_LONGITUDE>,
                  "name": "<LOCATION_NAME>" #Optional
                },
                "type": "location"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Webhook Contents

Placeholder	Description	Example Value
<LOCATION_ADDRESS> String	Location address. This parameter will only appear if the WhatsApp user chooses to share it.	1071 5th Ave, New York, NY 10128
<LOCATION_LATITUDE> Number	Location latitude in decimal degrees.	40.782910059774
<LOCATION_LONGITUDE> Number	Location longitude in decimal degrees.	-73.959075808525
<LOCATION_NAME> String	Location name. This parameter will only appear if the WhatsApp user chooses to share it.	Solomon R. Guggenheim Museum
<TIMESTAMP> String	UNIX timestamp indicating when our servers processed the WhatsApp user's message.	1702920965
<WHATSAPP_BUSINESS_ACCOUNT_ID> String	WhatsApp Business Account ID.	102290129340398
<WHATSAPP_BUSINESS_DISPLAY_PHONE_NUMBER> String	WhatsApp business phone number's display number.	15550783881
<WHATSAPP_BUSINESS_PHONE_NUMBER> String	WhatsApp business phone number.	15550783881
<WHATSAPP_BUSINESS_PHONE_NUMBER_ID> String	WhatsApp business phone number ID.	106540352242922
<WHATSAPP_CONTEXT_MESSAGE_ID> String	WhatsApp message ID of message that the user is responding to.	wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI1QjJGRjI1RDY0RkE4Nzg4QzcA
<WHATSAPP_MESSAGE_ID> String	WhatsApp message ID of the user's message.	wamid.HBgLMTY0NjcwNDM1OTUVAgASGBQzQTRCRDcwNzgzMTRDNTAwRTgwRQA=
<WHATSAPP_USER_ID> String	WhatsApp user's WhatsApp ID.	16467043595
<WHATSAPP_USER_NAME> String	WhatsApp user's name.	Pablo Morales

Example Webhook

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "15550783881",
              "phone_number_id": "106540352242922"
            },
            "contacts": [
              {
                "profile": {
                  "name": "John Doe"
                },
                "wa_id": "15551234567"
              }
            ],
            "messages": [
              {
                "context": {
                  "from": "15550783881",
                  "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI1QjJGRjI1RDY0RkE4Nzg4QzcA"
                },
                "from": "15551234567",
                "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgASGBQzQTRCRDcwNzgzMTRDNTAwRTgwRQA=",
                "timestamp": "1702920965",
                "location": {
                  "address": "1071 5th Ave, New York, NY 10128",
                  "latitude": 40.782910059774,
                  "longitude": -73.959075808525,
                  "name": "Solomon R. Guggenheim Museum"
                },
                "type": "location"
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

[will be deprecated] If the WABA is registered in On-premise API

As announced in November 2023, Meta is transitioning to a fully Cloud-hosted WhatsApp Business Platform and will stop supporting On-Premise API in October 2025. Starting from On-Premise client v2.53, all new feature updates will be exclusively delivered to Cloud API. While the On-Premise API client will receive quarterly releases, they will focus solely on bug fixes and security patches.

• See differences between On-premise API and Cloud API

• Enable Cloud API in your Partner Hub to be able to register Cloud API numbers

• Learn how to change hosting type of registered numbers

POST https://waba.360dialog.io/v1/messages

To send a message, use the request URL and the following body parameters.

Request Body

Name	Type	Description
recipient_type	string	individual
to*	string	wa_id of the contact you want to message
body.type	string	location_request_message
body.text	object	contains body field
action.name	String

201

A successful response includes a messages object with an ID for the newly created message.

{
    "messages": [
        {
            "id": "gBGHSRUUIXKJTwIJVQgXRR0rdXiv"
        }
    ],
    "meta": {
        "api_status": "stable",
        "version": "2.31.5"
    }
}

Post Body

{
  "type": "location_request_message",
  "body": {
    "type": "text",
    "text": "<TEXT>"
  },
  "action": {
    "name": "send_location" 
  }
}

If your message is sent successfully, you get the following response:

{
  "messages": [{
    "id": "{message-id}"
  }]
}