Send Location Messages
POST Method
The Send Location Messages API allows you to send a location based on latitude and longitude coordinates to a WhatsApp user.
Prerequisites
- Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.
A prerequisite for using Kaleyra WhatsApp APIs is to have an active WhatsApp plan on kaleyra platform. - To set up a WhatsApp account on kaleyra.io, see Manual Signup
and Embedded Signup. - An active WhatsApp for Business API plan that includes:
- A WhatsApp business number.
- An associated profile with the business number.
- A WhatsApp verified and approved profile.
- A WABA ID onboarded on Kaleyra WhatsApp API V2.
API Domain and Value
api_domain | Value |
---|---|
IN pod | api.in.kaleyra.io |
SG Pod | api.kaleyra.io |
EU Pod | api.eu.kaleyra.io |
NA pod | api.na.kaleyra.ai |
API request to send Location Messages
To send Location Messages, use the https://<api_domain>/v2/<sid>/whatsapp/<phone_number>/messages
endpoint with the following request method:
The following is the request format to send Location Messages:
curl -X POST \
https://<api_domain>/v2/<sid>/whatsapp/<phone_number>/messages \
-H 'Content-Type: application/json' \
-H 'api-key: <api-key>' \
-H 'cache-control: no-cache' \
-d '{
"messaging_object": {
"messaging_product": "<messaging_product>",
"to": "<to_number>",
"type": "<type>",
"location": {
"longitude": <location_longitutde>,
"latitude": <location_latitude>,
"name": "<location_name>",
"address": "<location_address>"
}
},
"extra_info": {
"ref": "<ref>",
"ref1": "<ref1>",
"ref2": "<ref2>",
"wa_source": "<wa_source>"
}
}'
The following is the sample request format to send Location Messages:
curl -X POST \
https://api.in.kaleyra.io/v2/HXAP16XXXXXX97IN/whatsapp/91XXXXXXXXXX/messages \
-H 'Content-Type: application/json' \
-H 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
-H 'cache-control: no-cache' \
-d '{
"messaging_object": {
"messaging_product": "whatsapp",
"to": "+91XXXXXXXXXX",
"type": "location",
"location": {
"longitude": 4x.78xxxxxxx74,
"latitude": -7x.95xxxxxxx525,
"name": "John Doe Street",
"address": "1051 Forest Avenue, IN"
}
},
"extra_info": {
"ref": "customer1",
"ref1": "marketing",
"ref2": "dictionary",
"wa_source": "api"
}
}'
Following is the list of parameters and data types supported for sending location messages:
Following is the list of attributes to be used in the payload to send the outgoing message:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
messaging_object | JSON object | Payload is supported only in JSON format. The messaging_object is the payload which contains the message object as defined by Meta which is used to send the WhatsApp message. | See the specific table for details. | Yes |
extra_info | JSON object | This object will contain additional details that a user can send for certain functionalities. | See the specific table for details. | No |
The following table describes the different attributes used for the messaging_object
JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
| String | Messaging service used for the request. | Only allowed value is whatsapp | Yes |
| String | A valid WhatsApp number of the recipient. Ensure that the country code is prefixed to the number. (E164 format). |
| Yes |
| String | The type of message you want to send. For sending location messages, the only allowed value is location. If omitted, defaults to text. | The only allowed value is location. | Yes |
| JSON Object | The longitude and latitude details for sharing the location. | See the specific table for details. | Yes |
The following table describes the different attributes used for the location
object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
longitude | Float | Location longitude in decimal degrees. | 4x.78xxxxxxx74 | Yes |
latitude | Float | Location latitude in decimal degrees. | -7x.95xxxxxxx525 | Yes |
name | String | Location name. | John Doe Street | No |
address | String | Location address. | 1051 Forest Avenue, IN | No |
The following table describes the different attributes used for the extra_info
JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
| String | Include any contextual information in this parameter you want to associate with the request. For Example, Name, Customer ID, and many more. | customer1 | No |
| String | Include the contextual information in this parameter you want to associate with the request. For Example, Name, Customer ID, and many more. | marketing | No |
| String | Include the contextual information in this parameter you want to associate with the request. For Example, Name, Customer ID, and many more. | dictionary | No |
| String | Indicates the source from where the API has been triggered. Supported values for wa_source are "api", "clevertap", "zoho", "webengage", "shopify", "leadsquared", "responsys", "braze", "hubspot", "salesforce", "zapier", "eloqua", and "moengage". | api | No |
Note:In the case of ref, ref1, and ref2, if the length of the string exceeds 255 characters, it will be truncated.
Sample Failure Response
The following are the failure responses:
401 Unauthorized
{
"code": "RBC001",
"message": "Incorrect SID or API key.",
"data": [],
"error": {
"error": "Incorrect SID or API key."
}
}
401 Unauthorized phone number
{
"code": "WA401",
"message": "Phone number is not present or does not belong to the account.",
"data": {},
"error": {
"phone_number": "Phone number is not present or does not belong to the account."
}
}
400 Incorrect payload
{
"code": "WA400",
"message": "Refer to correct payload format",
"data": {},
"error": {
"payload": "Incorrect payload format"
}
}
500 Internal Server Error
{
"code": "WA500",
"message": "Please try again later",
"data": {},
"error": {
"error": "Internal server error"
}
}
400 Low balance
{
"code": "E110",
"message": "Please check your balance, You have a low balance!",
"data": {},
"error": {
"balance": "Please check your balance, You have a low balance!"
}
}
401 Unauthorised Account type
{
"code": "WA-401",
"message": "API is not available for given customer.Please contact support for more info",
"data": {},
"error": {
"account": "API is not available for given customer.Please contact support for more info"
}
}
401 Unauthorized phone number version
{
"code": "WA-401",
"message": "The phone number you're using is associated with different Version of our WA API. Please use the appropriate endpoint.",
"data": {},
"error": {
"phone_number": "The phone number you're using is associated with different Version of our WA API. Please use the appropriate endpoint."
}
}
Updated 6 days ago