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.

1. [Create an API Key] .
   To view the API Key and the SID, see [View API Key
   and SID] .
2. 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
3. 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.

The following table describes the different address parameters used in the WhatsApp Address message API requests.