You can use the API to send the following free-form messages types:
All of these message types, except for reaction messages, can be designated as a reply, which causes the delivered message to appear along with a contextual bubble displaying the content of the message that you are replying to.
Use the POST WhatsApp Business Phone Number > Messages endpoint to send free-form messages to customers:
POST /<WHATSAPP_BUSINESS_PHONE_NUMBER>/messages
All free-form send message requests use the following object format.
{ "messaging_product": "whatsapp", "recipient_type": "individual", "to": "<TO>", "type": "<TYPE>", /* TEXT MESSAGES ONLY */ "text": {<TEXT>} /* REACTION MESSAGES ONLY */ "reaction": {<REACTION>} /* MEDIA MESSAGES ONLY. FOR EXAMPLE, FOR IMAGE MEDIA: */ "image": {<IMAGE>} /* LOCATION MESSAGES ONLY */ "location": {<LOCATION>} /* CONTACTS MESSAGES ONLY */ "contacts": {<CONTACTS>} /* INTERACTIVE MESSAGES ONLY */ "interactive": {<INTERACTIVE>} }
Placeholder | Description | Sample Value |
---|---|---|
String | The WhatsApp ID or phone number of the customer to send the message to. See Phone Number Formats |
|
String | Indicates message type. |
|
Object | Text messages contents. | See Text Messages. |
Object | Reaction message contents. | |
Object | Media message contents. The property name should match the type of media message you are sending ( | See Media Messages. |
Object | Location message contents. | |
Object | Contacts message contents. | See Contacts Messages. |
Object | Interactive message contents. | See Interactive Messages. |
The examples throughout this document describe the post body payload requirements for each of the free-form message types.
Upon success the API will respond with:
{ "messaging_product": "whatsapp", "contacts": [ { "input": "<WHATSAPP_USER_PHONE_NUMBER>", "wa_id": "<WHATSAPP_USER_ID>" } ], "messages": [ { "id": "<WHATSAPP_MESSAGE_ID>" } ] }
Placeholder | Description | Sample Value |
---|---|---|
String | WhatsApp user's WhatsApp phone number. May not match |
|
String | WhatsApp user's WhatsApp ID. May not match |
|
String | WhatsApp Message ID. This ID appears in associated messages webhooks, such as sent, read, and delivered webhooks. |
|
Plus signs (+
), hyphens (-
), parenthesis ((
,)
), and spaces are supported in send message requests.
We highly recommend that you include both the plus sign and country calling code when sending a message to a customer. If the plus sign is omitted, your business phone number's country calling code is prepended to the customer's phone number. This can result in undelivered or misdelivered messages.
For example, if your business is in India (country calling code 91
) and you send a message to the following customer phone number in various formats:
Number In Send Message Request | Number Message Delivered To | Outcome |
---|---|---|
|
| Correct number |
|
| Correct number |
|
| Potentially wrong number |
|
| Potentially wrong number |
To send a text message, make a POST
call to /PHONE_NUMBER_ID/messages
and attach a message object with type=text
. Then, add a text
object.
Sample request:
curl -X POST \
'https://graph.facebook.com/v19.0
/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE_NUMBER",
"type": "text",
"text": { // the text object
"preview_url": false,
"body": "MESSAGE_CONTENT"
}
}'
If you would like to add preview URL, add the preview_url
field:
curl -X POST \
'https://graph.facebook.com/v19.0
/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE_NUMBER",
"type": "text",
"text": { // the text object
"preview_url": true,
"body": "Message content including a URL begins with https:// or http://"
}
}'
A successful response includes an object with an identifier prefixed with wamid. Use the ID listed after wamid to track your message status.
{ "messaging_product": "whatsapp", "contacts": [{ "input": "PHONE_NUMBER", "wa_id": "WHATSAPP_ID", }] "messages": [{ "id": "wamid.ID", }] }
To send reaction messages, make a POST
call to /PHONE_NUMBER_ID/messages
and attach a message
object with type=reaction
. Then, add a reaction
object.
Sample request:
curl -X POST \
'https://graph.facebook.com/v19.0
/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE_NUMBER",
"type": "reaction",
"reaction": {
"message_id": "wamid.HBgLM...",
"emoji": "\uD83D\uDE00"
}
}'
If the message you are reacting to is more than 30 days old, doesn't correspond to any message in the conversation, has been deleted, or is itself a reaction message, the reaction message will not be delivered and you will receive a webhook with the code 131009
.
A successful response includes an object with an identifier prefixed with wamid. Use the ID listed after wamid to track your message status.
{ "messaging_product": "whatsapp", "contacts": [{ "input": "PHONE_NUMBER", "wa_id": "WHATSAPP_ID", }] "messages": [{ "id": "wamid.ID", }] }
Use the POST WhatsApp Business Phone Number > Messages endpoint to send a media message. Use the type
property to indicate the media asset's type (audio
, document
, image
, sticker
, or video
) and either the id
or link
property to indicate its ID (which you must generate) or location on your public server.
If using id
, you must first upload your media asset to our servers and capture the returned media ID. If using link
, your asset must be on a publicly accessible server or the message will fail to send.
To reduce the likelihood of errors and avoid unnecessary requests to your public server, we recommend that you upload your media assets and use their IDs when sending messages.
Media assets can also be cached. See Media HTTP Caching.
Sample request using image with link:
curl -X POST \
'https://graph.facebook.com/v19.0
/FROM-PHONE-NUMBER-ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE-NUMBER",
"type": "image",
"image": {
"link" : "https://IMAGE_URL"
}
}'
Sample request using media ID:
curl -X POST \
'https://graph.facebook.com/v19.0
/FROM-PHONE-NUMBER-ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE-NUMBER",
"type": "image",
"image": {
"id" : "MEDIA-OBJECT-ID"
}
}'
A successful response includes an object with an identifier prefixed with wamid. If you are using a link to send the media, please check the callback events delivered to your Webhook server whether the media has been downloaded successfully.
{ "messaging_product": "whatsapp", "contacts": [{ "input": "PHONE_NUMBER", "wa_id": "WHATSAPP_ID", }] "messages": [{ "id": "wamid.ID", }] }
The Cloud API supports media HTTP caching. If you are using a link (link
) to a media asset on your server (as opposed to the ID (id
) of an asset you have uploaded to our servers), you can instruct us to cache your asset for reuse with future messages by including the headers below in your server response when we request the asset. If none of these headers are included, we will not cache your asset.
Cache-Control: <CACHE_CONTROL> Last-Modified: <LAST_MODIFIED> ETag: <ETAG>
The Cache-Control
header tells us how to handle asset caching. We support the following directives:
max-age=n
: Indicates how many seconds (n
) to cache the asset. We will reuse the cached asset in subsequent messages until this time is exceeded, after which we will request the asset again, if needed. Example: Cache-Control: max-age=604800
.no-cache
: Indicates the asset can be cached but should be updated if the Last-Modified
header value is different from a previous response. Requires the Last-Modified
header. Example: Cache-Control: no-cache
.no-store
: Indicates that the asset should not be cached. Example: Cache-Control: no-store
.private
: Indicates that the asset is personalized for the recipient and should not be cached.Indicates when the asset was last modified. Used with Cache-Control: no-cache
. If the Last-Modified
value is different from a previous response and Cache-Control: no-cache
is included in the response, we will update our cached version of the asset with the asset in the response. Example: Date: Tue, 22 Feb 2022 22:22:22 GMT
.
The ETag
header is a unique string that identifies a specific version of an asset. Example: ETag: "33a64df5"
. This header is ignored unless both Cache-Control
and Last-Modified
headers are not included in the response. In this case, we will cache the asset according to our own, internal logic (which we do not disclose).
HTTP/1.1 200 OK Content-Type: image/png Content-Length: 1024 Date: Tue, 22 Feb 2022 22:22:22 GMT ETag: "33a64df5" Cache-Control: max-age=604800 <IMAGE_PAYLOAD>
To send location messages, make a POST
call to /PHONE_NUMBER_ID/messages
and attach a message
object with type=location
. Then, add a location
object.
Sample request:
curl -X POST \
'https://graph.facebook.com/v19.0
/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"to": "PHONE_NUMBER",
"type": "location",
"location": {
"longitude": LONG_NUMBER,
"latitude": LAT_NUMBER,
"name": LOCATION_NAME,
"address": LOCATION_ADDRESS
}
}'
A successful response includes an object with an identifier prefixed with wamid. Use the ID listed after wamid to track your message status.
{ "messaging_product": "whatsapp", "contacts": [{ "input": "PHONE_NUMBER", "wa_id": "WHATSAPP_ID", }] "messages": [{ "id": "wamid.ID", }] }
To send contacts messages, make a POST
call to /PHONE_NUMBER_ID/messages
and attach a message
object with type=contact
. Then, add a contacts
object.
Sample request:
curl -X POST \
'https://graph.facebook.com/v19.0
/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"to": "PHONE_NUMBER",
"type": "contacts",
"contacts": [{
"addresses": [{
"street": "STREET",
"city": "CITY",
"state": "STATE",
"zip": "ZIP",
"country": "COUNTRY",
"country_code": "COUNTRY_CODE",
"type": "HOME"
},
{
"street": "STREET",
"city": "CITY",
"state": "STATE",
"zip": "ZIP",
"country": "COUNTRY",
"country_code": "COUNTRY_CODE",
"type": "WORK"
}],
"birthday": "YEAR_MONTH_DAY",
"emails": [{
"email": "EMAIL",
"type": "WORK"
},
{
"email": "EMAIL",
"type": "HOME"
}],
"name": {
"formatted_name": "NAME",
"first_name": "FIRST_NAME",
"last_name": "LAST_NAME",
"middle_name": "MIDDLE_NAME",
"suffix": "SUFFIX",
"prefix": "PREFIX"
},
"org": {
"company": "COMPANY",
"department": "DEPARTMENT",
"title": "TITLE"
},
"phones": [{
"phone": "PHONE_NUMBER",
"type": "HOME"
},
{
"phone": "PHONE_NUMBER",
"type": "WORK",
"wa_id": "PHONE_OR_WA_ID"
}],
"urls": [{
"url": "URL",
"type": "WORK"
},
{
"url": "URL",
"type": "HOME"
}]
}]
}'
A successful response includes an object with an identifier prefixed with wamid. Use the ID listed after wamid to track your message status.
{ "messaging_product": "whatsapp", "contacts": [{ "input": "PHONE_NUMBER", "wa_id": "WHATSAPP_ID", }] "messages": [{ "id": "wamid.ID", }] }
Interactive messages include list messages, reply buttons, click-to-action URL buttons, and Flows messages. To send interactive messages, make a POST
call to /PHONE_NUMBER_ID/messages
and attach a message object with type=interactive
. Then, add an interactive
object.
Example request:
curl -X POST \
'https://graph.facebook.com/v19.0
/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE_NUMBER",
"type": "interactive",
"interactive": {
"type": "list",
"header": {
"type": "text",
"text": "HEADER_TEXT"
},
"body": {
"text": "BODY_TEXT"
},
"footer": {
"text": "FOOTER_TEXT"
},
"action": {
"button": "BUTTON_TEXT",
"sections": [
{
"title": "SECTION_1_TITLE",
"rows": [
{
"id": "SECTION_1_ROW_1_ID",
"title": "SECTION_1_ROW_1_TITLE",
"description": "SECTION_1_ROW_1_DESCRIPTION"
},
{
"id": "SECTION_1_ROW_2_ID",
"title": "SECTION_1_ROW_2_TITLE",
"description": "SECTION_1_ROW_2_DESCRIPTION"
}
]
},
{
"title": "SECTION_2_TITLE",
"rows": [
{
"id": "SECTION_2_ROW_1_ID",
"title": "SECTION_2_ROW_1_TITLE",
"description": "SECTION_2_ROW_1_DESCRIPTION"
},
{
"id": "SECTION_2_ROW_2_ID",
"title": "SECTION_2_ROW_2_TITLE",
"description": "SECTION_2_ROW_2_DESCRIPTION"
}
]
}
]
}
}
}'
Example request:
curl -X POST \
'https://graph.facebook.com/v19.0
/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE_NUMBER",
"type": "interactive",
"interactive": {
"type": "button",
"body": {
"text": "BUTTON_TEXT"
},
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"id": "UNIQUE_BUTTON_ID_1",
"title": "BUTTON_TITLE_1"
}
},
{
"type": "reply",
"reply": {
"id": "UNIQUE_BUTTON_ID_2",
"title": "BUTTON_TITLE_2"
}
}
]
}
}
}'
A successful response includes an object with an identifier prefixed with wamid. Use the ID listed after wamid to track your message status.
{ "messaging_product": "whatsapp", "contacts": [{ "input": "PHONE_NUMBER", "wa_id": "WHATSAPP_ID", }] "messages": [{ "id": "wamid.ID", }] }
Your customers may be hesitant to tap raw URLs containing lengthy or obscure strings in text messages. In these situations, you may wish to send an interactive message with body text and a call-to-action (CTA) URL button.
CTA URL buttons allow you to map any URL to a button so you don't have to include the raw URL in the interactive message body.
POST /<BUSINESS_PHONE_NUMBER_ID>/messages
{ "messaging_product": "whatsapp", "recipient_type": "individual", "to": "<CUSTOMER_PHONE_NUMBER>", "type": "interactive", "interactive": { "type": "cta_url", /* Header optional */ "header": { "type": "text", "text": "<HEADER_TEXT>" }, /* Body optional */ "body": { "text": "<BODY_TEXT>" }, /* Footer optional */ "footer": { "text": "<FOOTER_TEXT>" }, "action": { "name": "cta_url", "parameters": { "display_text": "<BUTTON_TEXT>", "url": "<BUTTON_URL>" } } } }
Placeholder | Description | Sample Value |
---|---|---|
String | Required. The WhatsApp ID or phone number of the customer the message is being sent to. See Phone Number Formats. |
|
String | Optional. Header text. |
|
String | Required. Message body text. |
|
String | Optional. Message footer text. |
|
String | Required. Button text. |
|
String | Required. URL to load in the device's default web browser when tapped by the WhatsApp user. |
|
curl 'https://graph.facebook.com/v19.0
/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "+16505555555",
"type": "interactive",
"interactive": {
"type": "cta_url",
"header": {
"text": "Available Dates"
},
"body": {
"text": "Tap the button below to see available dates."
},
"footer": {
"text": "Dates subject to change."
},
"action": {
"name": "cta_url",
"parameters": {
"display_text": "See Dates",
"url": "https://www.luckyshrub.com?clickID=kqDGWd24Q5TRwoEQTICY7W1JKoXvaZOXWAS7h1P76s0R7Paec4"
}
}
}
}'
{ "messaging_product": "whatsapp", "contacts": [ { "input": "+16505555555", "wa_id": "+16505555555" } ], "messages": [ { "id": "wamid.HBgLMTY1MDUwNzY1MjAVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA" } ] }
After you create a WhatsApp Flow, you can send it. To send a message with a flow, we have introduced a new type of the Interactive Object called flow
. These are the following properties of the Interactive Object specific to flows:
Property | Type | Description |
---|---|---|
| String | Value must be |
| String | Value must be |
| String | The Flow can be in either |
| String | Value must be |
| String | Flow token that is generated by the business to serve as an identifier. |
| String | Unique ID of the Flow provided by WhatsApp. |
| String | Text on the CTA button. For example: "Signup" Character limit - 20 characters (no emoji). |
| String |
|
| String | Required if |
| String | The |
| String | Optional. The input data for the first screen of the Flow. Must be a non-empty object. |
Example Request
curl -X POST \ 'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "recipient_type": "individual", "messaging_product": "whatsapp", "to": "PHONE_NUMBER", "type": "interactive", "interactive": { "type": "flow", "header": { "type": "text", "text": "Flow message header" }, "body": { "text": "Flow message body" }, "footer": { "text": "Flow message footer" }, "action": { "name": "flow", "parameters": { "flow_message_version": "3", "flow_token": "AQAAAAACS5FpgQ_cAAAAAD0QI3s.", "flow_id": "1", "flow_cta": "Book!", "flow_action": "navigate", "flow_action_payload": { "screen": "<SCREEN_NAME>", "data": { "product_name": "name", "product_description": "description", "product_price": 100 } } } } } }'
Example Response
{ "messaging_product": "whatsapp", "contacts": [ { "Input": "PHONE_NUMBER", "wa_id": "WHATSAPP_ID" } ], "messages": [ { "id": "wamid.ID" } ] }
You can send any message as a reply to a previous message in a conversation by including the previous message's ID in the context
object. The recipient will receive the new message along with a contextual bubble that displays the previous message's content.
Recipients will not see a contextual bubble if:
"type":"template"
)These are known bugs which we are addressing.
Sample request:
curl -X POST \
'https://graph.facebook.com/v19.0
/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: ACCESS_TOKEN' \
-d '{
"messaging_product": "whatsapp",
"context": {
"message_id": "MESSAGE_ID"
},
"to": "<phone number> or <wa_id>",
"type": "text",
"text": {
"preview_url": False,
"body": "your-text-message-content"
}
}'
A successful response includes an object with an identifier prefixed with wamid. Use the ID listed after wamid to track your message status.
Note: if the previous message is more than 30 days old or doesn't correspond to any message in the conversation, the message will be sent normally instead of as a reply.
Sample response:
{ "messaging_product": "whatsapp", "contacts": [{ "input": "PHONE_NUMBER", "wa_id": "WHATSAPP_ID", }] "messages": [{ "id": "wamid.ID", }] }
This feature is only available for businesses based in Singapore and their Singapore customers, and businesses based in India and their India customers.
Address messages give your users a simpler way to share the shipping address with the business on WhatsApp.
Address messages are interactive messages that contain the 4 main parts: header
, body
, footer
, and action
. Inside the action component business specifies the name “address_message” and relevant parameters.
Currently address messages are supported in the following two countries: India and Singapore. Below table outlines which fields are supported in which country specifically.
Field Name | Display Label | Input Type | Supported Countries | Limitations |
---|---|---|---|---|
| Name | text | India, Singapore | None |
| Phone Number | tel | India, Singapore | Valid phone numbers only |
| Pin Code | text | India | Max length: 6 |
| Post Code | number | Singapore | Max length: 6 |
| Flat/House Number | text | India | None |
| Floor Number | text | India | None |
| Tower Number | text | India | None |
| Building/Apartment Name | text | India | None |
| Address | text | India, Singapore | None |
| Landmark/Area | text | India | None |
| Unit number | text | Singapore | None |
| City | text | India, Singapore | None |
| State | text | India | None |
This is a sample API call for the address message. The country
attribute is a mandatory field in the action parameters. If it is not included, there will be a validation error.
curl -X POST \ 'https://graph.facebook.com/v15.0/FROM_PHONE_NUMBER_ID/messages' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "messaging_product": "whatsapp", "recipient_type": "individual", "to": "PHONE_NUMBER", "type": "interactive", "interactive": { "type": "address_message", "body": { "text": "Thanks for your order! Tell us what address you’d like this order delivered to." }, "action": { "name": "address_message", "parameters": { "country" :"COUNTRY_ISO_CODE" } } } }'
If the area code of the phone number for the given country is not correct, businesses will be unable to request the address message from the recipient. For example, businesses will be unable to request an address message from a recipient that has the country as “Singapore” but has a phone number with an area code of "91".
Address messages will not allow simultaneous passing of conflicting fields. For example, you cannot pass in
sg_post_code
when country
is set to “IN”.
Once the address message is sent, the business waits for the user to fill in the address and send it back. The user entered address is shared through the webhook registered in the setup process.
The steps involved in an Address Message are the following:
address_message
to the userThe following sequence diagram shows a typical integration flow for an address message.
The business can pass additional attributes such as values
, validation_errors
, or saved_addresses
as part of the interactive action parameters. You can find information on each of their usage below.
Action Parameter | Usage |
---|---|
| Businesses prefill this for address fields (eg. prefilling the city address field with “Singapore”) |
| For businesses, they can pass in saved addresses previously associated with the user. For users, they are presented with the option to choose the saved address instead of manually filling it in |
| Businesses can throw errors in the address fields and WhatsApp will prevent the user from submitting the address until the issue(s) are/is resolved. |
Make a POST
call to /PHONE_NUMBER_ID/messages
using the WhatsApp API to send an end-to-end encrypted address message to the user:
curl -X POST \ 'https://graph.facebook.com/v15.0/FROM_PHONE_NUMBER_ID/messages' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d ' { "messaging_product": "whatsapp", "recipient_type": "individual", "to": "PHONE_NUMBER", "type": "interactive", "interactive": { "type": "address_message", "body": { "text": "Thanks for your order! Tell us what address you’d like this order delivered to." }, "action": { "name": "address_message", "parameters": "JSON Payload" } } }'
To send an address message without any saved addresses, WhatsApp will prompt the user or business with an address form to enter a new address.
curl -X POST \ 'https://graph.facebook.com/v15.0/FROM_PHONE_NUMBER_ID/messages' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "messaging_product": "whatsapp", "recipient_type": "individual", "to": "+91xxxxxxxxxx", "type": "interactive", "interactive": { "type": "address_message", "body": { "text": "Thanks for your order! Tell us what address you’d like this order delivered to." }, "action": { "name": "address_message", "parameters": { "country": "IN", "values": { "name": "CUSTOMER_NAME", "phone_number": "+91xxxxxxxxxx" } } } } }'
curl -X POST \ 'https://graph.facebook.com/v15.0/FROM_PHONE_NUMBER_ID/messages' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "messaging_product": "whatsapp", "recipient_type": "individual", "to": "+65xxxxxxxxxx", "type": "interactive", "interactive": { "type": "address_message", "body": { "text": "Thanks for your order! Tell us what address you’d like this order delivered to." }, "action": { "name": "address_message", "parameters": { "country": "SG", "values": { "name": "CUSTOMER_NAME", "phone_number": "+65xxxxxxxxxx" } } } } }'
To send an address message with saved addresses, WhatsApp will prompt the user or business with an option to select among the saved addresses or add an address option. Users can ignore the saved address and enter a new address.
curl -X POST \ 'https://graph.facebook.com/v15.0/FROM_PHONE_NUMBER_ID/messages' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "messaging_product": "whatsapp", "recipient_type": "individual", "to": "91xxxxxxxxxx", "type": "interactive", "interactive": { "type": "address_message", "body": { "text": "Thanks for your order! Tell us what address you’d like this order delivered to." }, "action": { "name": "address_message", "parameters": { "country": "IN", "saved_addresses": [ { "id": "address1", "value": { "name": "CUSTOMER_NAME", "phone_number": "+91xxxxxxxxxx", "in_pin_code": "400063", "floor_number": "8", "building_name": "", "address": "Wing A, Cello Triumph,IB Patel Rd", "landmark_area": "Goregaon", "city": "Mumbai" } } ] } } } }'
curl -X POST \ 'https://graph.facebook.com/v15.0/FROM_PHONE_NUMBER_ID/messages' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "messaging_product": "whatsapp", "recipient_type": "individual", "to": "+65xxxxxxxxxx", "type": "interactive", "interactive": { "type": "address_message", "body": { "text": "Thanks for your order! Tell us what address you’d like this order delivered to." }, "action": { "name": "address_message", "parameters": { "country": "SG", "values": { "name": "CUSTOMER_NAME", "phone_number": "+65xxxxxxxxxx" }, "saved_addresses": [ { "id": "address1", "value": { "name": "CUSTOMER_NAME", "phone_number": "+65xxxxxxxxxx", "sg_post_code": "018937", "address": "9 Straits View, Marina One West Tower", "unit_number": "Suite 29-00", "city": "Singapore" } } ] } } } }'
A successful response includes a messages
object with an ID for the newly created message.
{ "messaging_product": "whatsapp", "contacts": [{ "input": "PHONE_NUMBER", "wa_id": "WHATSAPP_ID", }] "messages": [{ "id": "wamid.ID", }] }
An unsuccessful response contains an error message. See Error and Status Codes for more information.
An address message should be re-sent to the user in the case of a validation error on the business server. The business should send back the set of values previously entered by the user, along with the respective validation errors for each invalid field, as shown in the sample payloads below.
curl -X POST \ 'https://graph.facebook.com/v15.0/FROM_PHONE_NUMBER_ID/messages' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "messaging_product": "whatsapp", "recipient_type": "individual", "to": "91xxxxxxxxxx", "type": "interactive", "interactive": { "type": "address_message", "body": { "text": "Thanks for your order! Tell us what address you’d like this order delivered to." }, "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": { "in_pin_code": "We could not locate this pin code." } } } } }'
curl -X POST \ 'https://graph.facebook.com/v15.0/FROM_PHONE_NUMBER_ID/messages' \ -H 'Authorization: Bearer ACCESS_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "messaging_product": "whatsapp", "recipient_type": "individual", "to": "12065550107", "type": "interactive", "interactive": { "type": "address_message", "body": { "text": "Thanks for your order! Tell us what address you’d like this order delivered to." }, "action": { "name": "address_message", "parameters": { "country": "SG", "values": { "name": "CUSTOMER_NAME", "phone_number": "+65xxxxxxxxxx", "sg_post_code": "666666", "address": "Some other location", "city": "Singapore" }, "validation_errors": { "sg_post_code": "We could not locate this pin code." } } } } }'
Businesses will receive address submission notifications through webhooks, such as the one shown below.
{ "messages": [ { "id": "gBGGFlAwCWFvAgmrzrKijase8yA", "from": "PHONE_NUMBER", "Interactive": { "type": "nfm_reply", "action": "address_message", "nfm_reply": { "name": "address_message", "response_json": “<response_json from client>”, "body": “<body text from client>”, } "timestamp": "1670394125", "type": "interactive" } ] }
The webhook notification has the following values.
Field Name | Type | Description |
---|---|---|
| Object | Holds the response from the client |
| String | Would be |
| Object | Holds the data received from the client |
| String | The values of the address fields filled by the user in JSON format that are always present |
| String | Body text from client, what the user sees |
| String | Would be |
An address message reply as an NFM response type for an India address message request is shown below.
{ "messages": [ { "context": { "from": "FROM_PHONE_NUMBER_ID", "id": "wamid.HBgLMTIwNjU1NTAxMDcVAgARGBI3NjNFN0U5QzMzNDlCQjY0M0QA" }, "from": "PHONE_NUMBER", "id": "wamid.HBgLMTIwNjU1NTAxMDcVAgASGCA5RDhBNENEMEQ3RENEOEEzMEI0RUExRDczN0I1NThFQwA=", "timestamp": "1671498855", "type": "interactive", "interactive": { "type": "nfm_reply", "nfm_reply": { "response_json": "{\"saved_address_id\":\"address1\",\"values\":{\"in_pin_code\":\"400063\",\"building_name\":\"\",\"landmark_area\":\"Goregaon\",\"address\":\"Wing A, Cello Triumph, IB Patel Rd\",\"city\":\"Mumbai\",\"name\":\"CUSTOMER_NAME\",\"phone_number\":\"+91xxxxxxxxxx\",\"floor_number\":\"8\"}}", "body": "CUSTOMER_NAME\n +91xxxxxxxxxx\n 400063, Goregaon, Wing A, Cello Triumph,IB Patel Rd, Mumbai, 8", "name": "address_message" } } } ] }
In the case where the client does not support address_message
, messages are silently dropped and an error message is sent back to the business in a webhook. The webhook notification that would be sent back is shown below:
{ "statuses": [ { "errors": [ { "code": 1026, "href": "https://developers.facebook.com/docs/whatsapp/api/errors/", "title": "Receiver Incapable" } ], "id": "gBGGFlAwCWFvAgkyHMGKnRu4JeA", "message": { "recipient_id": "+91xxxxxxxxxx" }, "recipient_id": "91xxxxxxxxxx", "status": "failed", "timestamp": "1670394125", "type": "message" } ] }
When sending a series of messages, the order in which messages are delivered is not guaranteed to match the order of your API requests. If you need to ensure the sequence of message delivery, confirm receipt of a delivered
status in a messages webhook before sending the next message in your message sequence.
If you are experiencing problems with message delivery, see Message Not Delivered.