You can use the API to send the following types of messages. All of these types, except for reaction messages, can be sent as a reply to a previous message.
Address messages allow you to easily request a delivery address from WhatsApp users. | |
Audio messages display an audio icon and a link to an audio file. When the WhatsApp user taps the icon, the WhatsApp client loads and plays the audio file. | |
Contacts messages allow you to send rich contact information directly to WhatsApp users, such as names, phone numbers, physical addresses, and email addresses. | |
Document messages display a document icon, linked to a document that a WhatsApp user can tap to download. | |
Image messages display a single image and an optional caption. | |
Interactive CTA URL button messages allow you to map any URL to a button, so you don't have to include lengthy or obscure raw URLs in the message body. | |
Interactive Flow messages allow you to send structured messages that are more natural or comfortable for your customers. For example, you can use WhatsApp Flows to book appointments, browse products, collect customer feedback, get new sales leads, or anything else. | |
Interactive list messages allow you to present WhatsApp users with a list of options to choose from. | |
Interactive location request messages display body text and a send location button. When a WhatsApp user taps the button, a location sharing screen appears which the user can use to share their location. | |
Interactive reply buttons messages allow you to send up to three predefined replies for users to choose from. | |
Location messages allow you to send a location's latitude and longitude coordinates to a WhatsApp user. | |
Sticker messages display animated or static sticker images in a WhatsApp message. | |
Text messages are messages containing only a text body and an optional link preview. | |
Template messages allow you to send marketing, utility, and authentication templates to WhatsApp users. Unlike all other message types, template messages do not require a 24-hour customer service window to be open between you and the message recipient before the message can be sent. | |
Video messages display a thumbnail preview of a video image with an optional caption. When the WhatsApp user taps the preview, it loads the video and displays it to the user. | |
Reaction messages are emoji-reactions that you can apply to a previous WhatsApp user message that you have received. |
Use the POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID/messages endpoint to send any type of message to a WhatsApp user who has opted-in to receiving messages from you:
POST /<WHATSAPP_BUSINESS_PHONE_NUMBER>/messages
All message send requests use the following generic post body format.
{ "messaging_product": "whatsapp", "recipient_type": "individual", "to": "<WHATSAPP_USER_PHONE_NUMBER>", "type": "<MESSAGE_TYPE>", "<MESSAGE_TYPE>": {<MESSAGE_CONTENTS>} }
For example, here's a sample request to send a text message with a preview link to a 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": "+16505551234",
"type": "text",
"text": {
"preview_url": true,
"body": "As requested, here'\''s the link to our latest product: https://www.meta.com/quest/quest-3/"
}
}'
Refer to the dedicated document for each message type to learn what each type can do and how to structure its send message request payload.
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 |
Media assets sent in messages must be uploaded to the business phone number that will be sending the message, or you must host the asset on a public server and include its URL in the message send request.
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.
WhatsApp 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>
Commerce messages are interactive messages used in conjunction with a product catalog. See Share Products With Customers to see how to use these types of messages.
You can send any type of message as a reply to a previous message. The previous message will appear at the top of the new message, quoted within a contextual bubble.
The contextual bubble will not appear at the top of the delivered message sent as a reply if:
POST /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>/messages
{ "messaging_product": "whatsapp", "recipient_type": "individual", "to": "<WHATSAPP_USER_PHONE_NUMBER>", "context": { "message_id": "WAMID_TO_REPLY_TO" }, /* Message type and type contents goes here */ }
Placeholder | Description | Example Value |
---|---|---|
String | Required. WhatsApp message ID (wamid) of the previous message you want to reply to. |
|
String | Required. WhatsApp user phone number. |
|
Example of a text message sent as a reply to a previous message.
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": "+16505551234", "context": { "message_id": "wamid.HBgLMTY0NjcwNDM1OTUVAgASGBQzQTdCNTg5RjY1MEMyRjlGMjRGNgA=" }, "type": "text", "text": { "body": "You'\''re welcome, Pablo!" } }'
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.