Send an Interactive WhatsApp Address Message
The ‘WhatsApp Address Messages’ feature allows brands and their end-users based in India (IN) or Singapore (SN) to exchange information about their addresses in a structured and standardized format directly within WhatsApp messages. This feature enables easier fetching of address information from WhatsApp messages by the brands and also serves as a better way to store such information in brands' systems, such as CRM or Order Fulfillment systems.
In case, an address provided by an end-user for any reason cannot be processed by the brand’s system (e.g. brand is not offering the services in the given region, then the brand can send back to the end-user an address message with validation errors, requesting the end-user to provide a different address.
NOTE:
This feature is available only in the IN and SG regions.
The feature handles the following types of messages:
- Brand can send an empty Address Message to the end-user and receive a new address from the end customer in a predefined format. In this case, the ‘Address Message’ is shown on the end-user device as a form to be filled with the address information.
- Brand can share the already saved address (one or more) with the customers for confirmation and if needed, accept a new address from the end customer. In this case the ‘Address Message’ is shown on the end-user device as a pre-filled form. The customers can also enter the new address.
- Request the end-user to provide a different address, when the address provided by the end-user is not operable (the address that the business does not operate within the country in which the feature is enabled). In this case, the address that needs to be changed by the end-user is highlighted.
The following screens show examples of the WhatsApp address message formats and the validation error message.
For sending a WhatsApp Address message, follow the steps below.
- [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.io.
To set up a WhatsApp account on Kaleyra.io, see: https://developers.kaleyra.io/docs/manual-signup
And
https://developers.kaleyra.io/docs/embedded-signup - Send the Address Message API request.
Sample Request for Address message
A business sends a WhatsApp address message API to the end customer to enter the new address.
curl --location request POST 'https://api.kaleyra.io/v1/<sid>/messages' \
--header 'api-key: <apikey>' \
--form 'to="9163836xxxxx"' \
--form 'type="address_message"' \
--form 'channel="whatsapp"' \
--form 'from="+9180496xxxxx"' \
--form 'body="Thanks for your order! Tell us what address you’d like this order delivered to."' \
--form 'action="{
\"name\": \"address_message\",
\"parameters\": {
\"country\" :\"XX\"
}
}"' \
--form 'callback_url="https://webhook.site/c8437dd1-7417-442c-a2a0-4d94aaxxxxxx'
Sample Response for Address message
A sample successful response for address message with response code '202' is shown.
{
"id": "038acf3e-e073-4e24-9a8e-94198bdd7aa1",
"type": "address_message",
"body": "Thanks for your order! Tell us what address you’d like this order delivered to.",
"createdDateTime": "2023-11-17 07:05:08+00:00",
"totalCount": 1,
"data": [
{
"message_id": "038acf3e-e073-4e24-9a8e-94198bdd7aa1:0",
"recipient": "xx63836xxxxx"
}
],
"error": {}
}
The below picture shows an example of how the end-user visualizes the address, once the form has been filled and the message is sent to the Brand.
Note:
- In all the three types of WhatsApp address messages, the 'Country' field is mandatory. The values allowed are 'IN' and 'SG'.
- The parameters in the API requests to accept addresses vary for different countries. For details, see the field description table provided at the end of this page.
- Replace the placeholders above with relevant values as mentioned in the field description tables.
Sample Request for Saved Address Message
In the following API request, Brands can have the already saved address information displayed on the end-user device. The end customer can either select one of the saved addresses or add a new address to complete the transaction.
curl --location request POST 'https://api.kaleyra.io//v1/<sid>/messages' \
--header 'api-key: <API>' \
--form 'to="91963836xxxxx"' \
--form 'type="address_message"' \
--form 'channel="whatsapp"' \
--form 'from="+9180496xxxxx"' \
--form 'body="Thanks for your order! Tell us what address you’d like this order delivered to."' \
--form 'action="{
\"name\": \"address_message\",
\"parameters\": {
\"country\": \"IN\",
\"saved_addresses\": [
{
\"id\": \"address10\",
\"value\": {
\"name\": \"CUSTOMER_NAME\",
\"phone_number\": \"+911234567xxx\",
\"in_pin_code\": \"400063\",
\"floor_number\": \"8\",
\"building_name\": \"\",
\"address\": \"Wing A, Cello Triumph,IB Patel Rd\",
\"landmark_area\": \"Goregaon\",
\"city\": \"Mumbai\"
}
},
{
\"id\": \"address1\",
\"value\": {
\"name\": \"CUSTOMER_NAME2\",
\"phone_number\": \"+911234567xxx\",
\"in_pin_code\": \"400063\",
\"floor_number\": \"8\",
\"building_name\": \"\",
\"address\": \"Wing A, Cello Triumph,IB Patel Rd\",
\"landmark_area\": \"Goregaon\",
\"city\": \"Mumbai\"
}
}
]
}
}"' \
--form 'callback_url="https://webhook.site/2ca83192-9bfc-481d-8012-9f24746bxxxx"' \
--form 'waba_id="209009789787xxxx"'
Sample Response for Saved Address Message
A sample successful response for saved address message with response code '202' is shown
{
"id": "08be4050-75ea-4745-b705-6168c5b839e0",
"type": "address_message",
"body": "Thanks for your order! Tell us what address you’d like this order delivered to.",
"createdDateTime": "2023-11-17 08:24:35+00:00",
"totalCount": 1,
"data": [
{
"message_id": "08be4050-75ea-4745-b705-6168c5b839e0:0",
"recipient": "9163836xxxxx"
}
],
"error": {}
}
Sample Request for Validation Error
In the following API request, the business requests the end-customers to provide a different address, if the validation of the address provided with the internal business system returns any error for a specific address field (e.g. the business is not operable in the address region). And, the field where the customer has to change the address is highlighted.
curl --location request POST 'https://api.kaleyra.io//v1/<sid>/messages' \
--header 'api-key:<API>' \
--form 'to="918637357739"' \
--form 'type="address_message"' \
--form 'channel="whatsapp"' \
--form 'from="+918049670237"' \
--form 'body="Thanks for your order! Tell us what address you’d like this order delivered to."' \
--form 'action="{
\"name\": \"address_message\",
\"parameters\": {
\"country\": \"IN\",
\"values\": {
\"name\": \"CUSTOMER_NAME\",
\"phone_number\": \"+91xxxxxxxxxx\",
\"in_pin_code\": \"666666\",
\"address\": \"Some other location\",
\"city\": \"Delhi\"
},
\"validation_errors\": {
\"city\": \"We could not locate this city.\"
}
}
}"' \
--form 'callback_url=""'
Sample Response for Validation Error
A sample successful response for validation error message with response code '202' is shown.
{
"id": "08292eb5-5125-4b17-9673-06b6394481d0",
"type": "address_message",
"body": "Thanks for your order! Tell us what address you’d like this order delivered to.",
"createdDateTime": "2023-11-17 08:33:49+00:00",
"totalCount": 1,
"data": [
{
"message_id": "08292eb5-5125-4b17-9673-06b6394481d0:0",
"recipient": "918637357739"
}
],
"error": {}
}
The following table describes the different parameters used in the WhatsApp Address message, Saved Address Message, and the Validation Error Message API requests.
Note:
The address fields vary for different countries. Use the appropriate fields based on the country to which you want to send the address message.
Parameter | Description | Example | Mandatory? |
---|---|---|---|
SID | Account SID (Security Identifier). Generated by Kaleyra.io while creating an API key. | HXXXXXXX071US | Yes |
content_type | Indicates the format of the content the API will be processing. | application/json | Yes |
api_key | Your API Key generated by Kaleyra.io. | Ac4XXXXX21f | Yes |
to_number | A valid WhatsApp number of the recipient. Ensure that the country code is prefixed to the number. (E164 format). Note: You can add multiple recipients, separate each number using the comma (,) delimiter. | +1202XXXXXXX | Yes |
message_type | Message format. For sending an address message, the only allowed value is address_message | address_message | Yes |
channel_name | Channel on which message must be sent. For WhatsApp channel, the only allowed value is WhatsApp. | Yes | |
from_number | The number registered with WhatsApp business from which the message is to be sent. Ensure that the country code is prefixed to the number. (E164 format). | +1202XXXXXXX | Yes |
callback_URL | The URL that Kaleyra.io should send information to, when your number receives a response(address values) from the customer. This URL can be accessed publicly. Click here for an example. | https://webhook.site/c8437dd1-7417-442c-a2a0-4d94aaxxxxxx | No |
callback_profile_id | The callback profile ID created for the WhatsApp incoming messages. For more information see: https://developers.kaleyra.io/docs/create-callback-profile-for-incoming-whatsapp-messages | xxxxx_2f40d4e7-960c-44d8-8abe-fdd4a35d038d | No |
body | Body of the message. | Your order has been shipped. | No |
action | The action object in the API request defines the fields that will be shown to the end-user and into which the data is sent back. In this case, the address values entered by the end customer are saved into the address fields described in the following table. | Yes |
The following table describes the different address parameters used in the WhatsApp Address message API requests.
Parameter | Description | Supported Countries | Example | Mandatory? |
---|---|---|---|---|
name | Name of the address | India, Singapore | Home address | Yes |
country | Name of the country for which the address values are accepted. The only allowed values are IN or SG(as per Meta). | India, Singapore | IN | Yes |
phone_number | Phone number of end customer. | India, Singapore | +91 99865xxxxx | Yes (valid phone numbers only) |
in_post_code | Pin code of the address in case the country is set to IN. | India | 560072 | No |
sg_post_code | Pin code of the address in case the country is set to SG. | Singapore | 238858 | No |
house_number | Flat/House number of the end customer. | India | 1120 | No |
floor_number | Floor number of the end customer. | India | 2 | No |
tower_number | Tower number of the end customer. | India | 12 | No |
building_name | Name of the building/apartment name. | India | Building 2 | No |
address | Address of the end customer | India, Singapore | xxxxx | No |
landmark_area | Landmark near the address of the end customer (if any). | India | xxxxxxxx | No |
unit_number | Unit number of the address | Singapore | 23 | No |
city | City in which the end customer resides. | India, Singapore | Singapore | No |
state | State to which the city belongs. | India | Karnataka | No |
Updated 11 days ago