Messages
- Sending messages | Developer Documentation
- Audio messages | Developer Documentation
- Contacts messages | Developer Documentation
- Document messages | Developer Documentation
- Image messages | Developer Documentation
- Interactive Call-to-Action URL Button Messages | Developer Documentation
- Interactive list messages | Developer Documentation
- Interactive media carousel messages | Developer Documentation
- Location messages | Developer Documentation
- Location request messages | Developer Documentation
- Reaction messages | Developer Documentation
- Template Messages | Developer Documentation
- Text messages | Developer Documentation
- Video Messages | Developer Documentation
- Mark messages as read | Developer Documentation
- Contextual replies | Developer Documentation
- Address Messages | Developer Documentation
Sending messages | Developer Documentation
Sending messages
Updated: Nov 4, 2025
This document describes how to use the API to send messages to WhatsApp users.
Message types
You can use the API to send the following types of messages.
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 voice call messages allow you to trigger WhatsApp call from users.
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 Flow messages are documented in our WhatsApp Flows documentation set.
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.
Message quality
Your message quality is based on how messages have been received by WhatsApp users over the past seven days and is weighted by recency. It is determined by a combination of user feedback signals like blocks, reports, mutes, archives, and reasons users provide when they block you.
Guidelines for sending high-quality messages:
Your business phone number’s status, quality rating, and messaging limits are displayed in the WhatsApp Manager > Account tools > Phone numbers panel.
Note that it is normal for numbers with high traffic to experience quality changes within short intervals (even within minutes).
Customer service windows
Whenever a WhatsApp user messages you or calls you, a 24-hour timer called a customer service window starts (or refreshes if one has already been started).
When a customer service window is open between you and a user, you can send any type of message to the user. If a window is not open between you and the user, you can only send template messages to the user, as template messages are the only type that can be sent outside of a customer service window.
As a reminder, you can only send messages to users who have opted-in to receiving messages from you.
Known issue: In rare cases, you may receive a message from a user but be unable to respond within the customer service window. We apologize for the inconvenience.
Commerce messages
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.
Read receipts
You can let a WhatsApp user know you have read their message by marking it as read, which causes two blue check marks (called “read receipts”) to appear below the user’s message:
Typing indicators
If it may take you a few seconds or more to respond to a WhatsApp user, you can let them know that you are preparing a response by display a typing indicator and read receipts in the WhatsApp client:
Contextual replies
You can send a message to a WhatsApp user as a contextual reply, which quotes a previous message in a contextual bubble:
This makes it easier for the user to know which specific message you are replying to.
WhatsApp user phone number formats
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 |
|---|---|---|
+16315551234 |
+16315551234 |
Correct number |
+1 (631) 555-1234 |
+16315551234 |
Correct number |
(631) 555-1234 |
+916315551234 |
Potentially wrong number |
1 (631) 555-1234 |
+9116315551234 |
Potentially wrong number |
Note: For Brazil and Mexico, the extra added prefix of the phone number may be modified by the Cloud API. This is a standard behavior of the system and is not considered a bug.
Media 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), WhatsApp Cloud API internally caches the asset for a static time period of 10 minutes. We will use the cached asset in subsequent send message requests if the link in subsequent message send payloads is the same as the link in the initial message send payload.If you don’t want us to reuse the cached asset in a subsequent message within the 10 minute time period, append a random query string to the asset link in the new send message request payload. We will treat this as a new asset, fetch it from your server, and cache it for 10 minutes.
For example:
https://link.to.media/sample.jpg — asset fetched, cached for 10 minutesAsset link in 2d send message request: https://link.to.media/sample.jpg - use cached assetAsset link in 3rd send message request: https://link.to.media/sample.jpg?abc123 - asset fetched, cached for 10 minutes
Delivery sequence of multiple messages
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 status messages webhook before sending the next message in your message sequence.Message Time-To-Live (TTL)
If we are unable to deliver a message to a WhatsApp user, we will retry the delivery for a period of time known as a time-to-live, TTL, or the message validity period.
Default TTL
Customizing TTL for templates
You can customize the default TTL for authentication and utility templates, and for marketing templates sent using the Marketing Messages API for WhatsApp. See our Time-to-live document to learn how.
When TTL is Exceeded: Dropped messages
Messages that are unable to be delivered within the default or customized TTL are dropped.
If you do not receive a status messages webhook with
status set to delivered before the TTL is exceeded, assume the message was dropped.If you send a message that fails (
status set to failed), there could be a minor delay before you receive the webhook, so you may wish to build in a small buffer before assuming the message was dropped.Troubleshooting
If you are experiencing problems with message delivery, see Message Not Delivered.
Audio messages | Developer Documentation
Audio messages
Updated: Feb 17, 2026
On March 17th, 2026, voice messages will start receiving a “played” status webhook the first time a WhatsApp user plays a voice message shared by the business.
You can use Cloud API to send voice messages and basic audio messages.
Voice messages
A voice message (sometimes referred to as a voice note, voice memo, or audio) is a recording of one or more persons speaking, and can include background sounds like music. Voice messages include features like automatic download, profile picture, and voice icon. These features are not available with basic audio messages. If the user sets voice message transcripts to Automatic, the message includes a text transcription.
Basic audio messages
Basic audio messages display a download icon and a music icon. When the WhatsApp user taps the play icon, the user manually download the audio message for the WhatsApp client to load and then play the audio file.
Request parameters
| Placeholder | Description | Example Value |
|---|---|---|
<ACCESS_TOKEN>String |
Required.
|
|
<API_VERSION>String |
Optional.
Graph API version. |
v25.0 |
<IS_VOICE?>Boolean |
Optional.
Set to
true if sending a voice message. Voice messages must be Ogg files encoded with the OPUS codec.To send a basic audio message, set to false or omit entirely. |
true |
<MEDIA_ID>String |
Required if using uploaded media, otherwise omit.
ID of the uploaded media asset. |
1013859600285441 |
<MEDIA_URL>String |
Required if using hosted media, otherwise omit.
URL of the media asset hosted on your public server. For better performance, we recommend using id and an uploaded media asset ID instead. |
https://www.luckyshrub.com/media/ringtones/wind-chime.mp3 |
<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>String |
Required.
WhatsApp business phone number ID. |
106540352242922 |
<WHATSAPP_USER_PHONE_NUMBER>String |
Required.
WhatsApp user phone number. |
+16505551234 |
Supported audio formats
| Audio Type | Extension | MIME Type | Max Size |
|---|---|---|---|
|
AAC |
.aac |
audio/aac |
16 MB |
|
AMR |
.amr |
audio/amr |
16 MB |
|
MP3 |
.mp3 |
audio/mpeg |
16 MB |
|
MP4 Audio |
.m4a |
audio/mp4 |
16 MB |
|
OGG Audio |
.ogg |
audio/ogg (OPUS codecs only; base audio/ogg not supported; mono input only) |
16 MB |
The most common errors associated with audio files are mismatched MIME types (MIME type doesn’t match the file type indicated by the file name) and invalid encoding for Ogg files (OPUS codec only). If you encounter an error when sending a media file, verify that your audio file’s MIME type matches its extension and is a supported type. For Ogg files, use the OPUS codec for encoding.
Contacts messages | Developer Documentation
Contacts messages
Updated: Nov 3, 2025
Contacts messages allow you to send rich contact information directly to WhatsApp users, such as names, phone numbers, physical addresses, and email addresses.
When a WhatsApp user taps the message's profile arrow, it displays the contact's information in a profile view:
Each message can include information for up to 257 contacts, although it is recommended to send fewer for usability and negative feedback reasons.
Please be aware that a contact's metadata (e.g., addresses, birthdays, emails) may not be supported by the recipient, especially on their primary device. Please refer to this documentation? for the definitions of primary and linked devices.
Request parameters
| Placeholder | Description | Example Value |
|---|---|---|
<ACCESS_TOKEN>String |
Required.
|
|
<ADDRESS_TYPE>String |
Optional.
Type of address, such as home or work. |
Home |
<API_VERSION>String |
Optional.
Graph API version. |
v25.0 |
<BIRTHDAY>String |
Optional.
Contact's birthday. Must be in YYYY-MM-DD format. |
1999-01-23 |
<CITY>String |
Optional.
City where the contact resides. |
Menlo Park |
<COMPANY_OR_ORG_NAME>String |
Optional.
Name of the company where the contact works. |
Lucky Shrub |
<COUNTRY_CODE>String |
Optional.
ISO two-letter country code. |
US |
<COUNTRY_NAME>String |
Optional.
Country name. |
United States |
<DEPARTMENT_NAME>String |
Optional.
Department within the company. |
Legal |
<EMAIL_ADDRESS>String |
Optional.
Email address of the contact. |
bjohnson@luckyshrub.com |
<EMAIL_TYPE>String |
Optional.
Type of email, such as personal or work. |
Work |
<FIRST_NAME>String |
Optional.
Contact's first name. |
Barbara |
<FORMATTED_NAME>String |
Required.
Contact's formatted name. This will appear in the message alongside the profile arrow button. |
Barbara J. Johnson |
<JOB_TITLE>String |
Optional.
Contact's job title. |
Lead Counsel |
<LAST_NAME>String |
Optional.
Contact's last name. |
Johnson |
<MIDDLE_NAME>String |
Optional.
Contact's middle name. |
Joana |
<PHONE_NUMBER>String |
Optional.
WhatsApp user phone number. |
+16505559999 |
<PHONE_NUMBER_TYPE>String |
Optional.
Type of phone number. For example, cell, mobile, main, iPhone, home, work, etc. |
Home |
<PREFIX>String |
Optional.
Prefix for the contact's name, such as Mr., Ms., Dr., etc. |
Dr. |
<STATE_CODE>String |
Optional.
Two-letter state code. |
CA |
<STREET_NUMBER_AND_NAME>String |
Optional.
Street address of the contact. |
1 Lucky Shrub Way |
<SUFFIX>String |
Optional.
Suffix for the contact's name, if applicable. |
Esq. |
<WEBSITE_TYPE>String |
Optional.
Type of website. For example, company, work, personal, Facebook Page, Instagram, etc. |
Company |
<WEBSITE_URL>String |
Optional.
Website URL associated with the contact or their company. |
https://www.luckyshrub.com |
<WHATSAPP_USER_ID>String |
Optional.
WhatsApp user ID. If omitted, the message will display an Invite to WhatsApp button instead of the standard buttons.
See Button Behavior below. |
19175559999 |
<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>String |
Required.
WhatsApp business phone number ID. |
106540352242922 |
<WHATSAPP_USER_PHONE_NUMBER>String |
Required.
WhatsApp user phone number. |
+16505551234 |
<ZIP_CODE>String |
Optional.
Postal or ZIP code. |
94025 |
If you include the contact's WhatsApp ID in the message (via the
wa_id property), the message will include a Message and a Save contact button:
If the WhatsApp user taps the Message button, it will open a new message with the contact. If the user taps the Save contact button, they will be given the option to save the contact as a new contact, or to update an existing contact.
If you omit the
wa_id property, both buttons will be replaced with an Invite to WhatsApp button:
Document messages | Developer Documentation
Document messages
Updated: Nov 3, 2025
Document messages are messages that display a document icon, linked to a document, that a WhatsApp user can tap to download.
Request parameters
| Placeholder | Description | Example Value |
|---|---|---|
<ACCESS_TOKEN>String |
Required.
|
|
<API_VERSION>String |
Optional.
Graph API version. |
v25.0 |
<MEDIA_CAPTION_TEXT>String |
Optional.
Media asset caption text.
Maximum 1024 characters. |
Lucky Shrub Invoice |
<MEDIA_FILENAME>String |
Optional.
Document filename, with extension. The WhatsApp client will use an appropriate file type icon based on the extension. |
lucky-shrub-invoice.pdf |
<MEDIA_ID>String |
Required if using uploaded media, otherwise omit.
ID of the uploaded media asset. |
1013859600285441 |
<MEDIA_URL>String |
Required if using hosted media, otherwise omit.
URL of the media asset hosted on your public server. For better performance, we recommend using id and an uploaded media asset ID instead. |
https://www.luckyshrub.com/invoices/FmOzfD9cKf/lucky-shrub-invoice.pdf |
<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>String |
Required.
WhatsApp business phone number ID. |
106540352242922 |
<WHATSAPP_USER_PHONE_NUMBER>String |
Required.
WhatsApp user phone number. |
+16505551234 |
Supported document types
| Document Type | Extension | MIME Type | Max Size |
|---|---|---|---|
|
Text |
.txt |
text/plain |
100 MB |
|
Microsoft Excel |
.xls |
application/vnd.ms-excel |
100 MB |
|
Microsoft Excel |
.xlsx |
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet |
100 MB |
|
Microsoft Word |
.doc |
application/msword |
100 MB |
|
Microsoft Word |
.docx |
application/vnd.openxmlformats-officedocument.wordprocessingml.document |
100 MB |
|
Microsoft PowerPoint |
.ppt |
application/vnd.ms-powerpoint |
100 MB |
|
Microsoft PowerPoint |
.pptx |
application/vnd.openxmlformats-officedocument.presentationml.presentation |
100 MB |
|
PDF |
.pdf |
application/pdf |
100 MB |
Only the above listed document types are officially supported and guaranteed to display correctly in the WhatsApp client. Other file types may be sent via the API, but they are not supported and may not be handled as expected.
Image messages | Developer Documentation
Image messages
Updated: Nov 3, 2025
Image messages are messages that display a single image and an optional caption.
Request parameters
| Placeholder | Description | Example Value |
|---|---|---|
<ACCESS_TOKEN>String |
Required.
|
|
<API_VERSION>String |
Optional.
Graph API version. |
v25.0 |
<MEDIA_CAPTION_TEXT>String |
Optional.
Media asset caption text.
Maximum 1024 characters. |
The best succulent ever? |
<MEDIA_ID>String |
Required if using uploaded media, otherwise omit.
ID of the uploaded media asset. |
1013859600285441 |
<MEDIA_URL>String |
Required if using hosted media, otherwise omit.
URL of the media asset hosted on your public server. For better performance, we recommend using id and an uploaded media asset ID instead. |
https://www.luckyshrub.com/assets/succulents/aloe.png |
<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>String |
Required.
WhatsApp business phone number ID. |
106540352242922 |
<WHATSAPP_USER_PHONE_NUMBER>String |
Required.
WhatsApp user phone number. |
+16505551234 |
Supported image formats
Images must be 8-bit, RGB or RGBA.
| Image Type | Extension | MIME Type | Max Size |
|---|---|---|---|
|
JPEG |
.jpeg |
image/jpeg |
5 MB |
|
PNG |
.png |
image/png |
5 MB |
Interactive Call-to-Action URL Button Messages | Developer Documentation
Interactive Call-to-Action URL Button Messages
Updated: Nov 3, 2025
WhatsApp users 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 call-to-action (CTA) URL button message instead. CTA URL button messages allow you to map any URL to a button so you don't have to include the raw URL in the message body.
Request parameters
| Placeholder | Description | Example Value |
|---|---|---|
<ACCESS_TOKEN>String |
Required.
|
|
<API_VERSION>String |
Optional.
Graph API version. |
v25.0 |
<ASSET_URL>String |
Required if using a header with a media asset.
Asset URL on a public server. |
https://www.luckyshrub.com/assets/lucky-shrub-banner-logo-v1.png |
<BODY_TEXT>String |
Required.
Body text. URLs are automatically hyperlinked.
Maximum 1024 characters. |
Tap the button below to see available dates. |
<BUTTON_LABEL_TEXT>String |
Required.
Button label text. Must be unique if using multiple buttons.
Maximum 20 characters. |
See Dates |
<BUTTON_URL> |
Required.
URL to load in the device's default web browser when tapped by the WhatsApp user. |
https://www.luckyshrub.com?clickID=kqDGWd24Q5TRwoEQTICY7W1JKoXvaZOXWAS7h1P76s0R7Paec4 |
<FOOTER_TEXT>String |
Required if using a footer.
Footer text. URLs are automatically hyperlinked.
Maximum 60 characters. |
Dates subject to change. |
<HEADER_TEXT>String |
Required if using a text header.
Header text.
Maximum 60 characters. |
New workshop dates announced! |
<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>String |
Required.
WhatsApp business phone number ID. |
106540352242922 |
<WHATSAPP_USER_PHONE_NUMBER>String |
Required.
WhatsApp user phone number. |
+16505551234 |
Interactive list messages | Developer Documentation
Interactive list messages
Updated: Nov 3, 2025
Interactive list messages allow you to present WhatsApp users with a list of options to choose from (options are defined as rows in the request payload):
When a user taps the button in the message, it displays a modal that lists the options available:
Users can then choose one option and their selection will be sent as a reply:
This triggers a webhook, which identifies the option selected by the user.
Interactive list messages support up to 10 sections, with up to 10 rows for all sections combined, and can include an optional header and footer.
Request parameters
| Placeholder | Description | Sample Value |
|---|---|---|
<ACCESS_TOKEN>String |
Required.
|
|
<API_VERSION>String |
Optional.
Graph API version. |
v25.0 |
<BUTTON_TEXT>String |
Required.
Button label text. When tapped, reveals rows (options the WhatsApp user can tap). Supports a single button.
Maximum 20 characters. |
Shipping Options |
<MESSAGE_BODY_TEXT>String |
Required.
Message body text. Supports URLs.
Maximum 4096 characters. |
Which shipping option do you prefer? |
<MESSAGE_FOOTER_TEXT>String |
Optional.
Message footer text.
Maximum 60 characters. |
Lucky Shrub: Your gateway to succulentsT |
<MESSAGE_HEADER_TEXT>String |
Optional.
The
header object is optional. Supports text header type only.Maximum 60 characters. |
Choose Shipping Option |
<ROW_DESCRIPTION_TEXT>String |
Optional.
Row description.
Maximum 72 characters. |
Next Day to 2 Days |
<ROW_ID>String |
Required.
At least one row is required. Supports up to 10 rows.
Maximum 200 characters. |
priority_express |
<ROW_TITLE_TEXT>String |
Required.
Row title. At least 1 row is required. Supports up to 10 rows.
Maximum 24 characters. |
Priority Mail Express |
<SECTION_TITLE_TEXT>String |
Required.
Section title text. At least 1 section is required. Supports up to 10 sections.
Maximum 24 characters. |
I want it ASAP! |
<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>String |
Required.
WhatsApp business phone number ID. |
106540352242922 |
<WHATSAPP_USER_PHONE_NUMBER>String |
Required.
WhatsApp user phone number. |
+16505551234 |
Interactive media carousel messages | Developer Documentation
Interactive media carousel messages
Updated: Dec 22, 2025
Interactive media carousel messages display a set of horizontally scrollable media cards. Each card can display an image or video header, body text, and either quick-reply buttons or a URL button.
For example, this is an interactive media card carousel message showing three cards in a scrollable area (highlighted by a dotted rectangle), each with an image header, body text, and URL button:
This is the same message, but using quick-reply buttons instead of URL buttons:
Components
Request parameters
| Placeholder | Description | Example value |
|---|---|---|
<ACCESS_TOKEN>String |
Required. Access token. |
EAAJB... |
<API_VERSION>String |
Optional. API version. |
v23.0 |
<BUSINESS_PHONE_NUMBER_ID>Integer |
Required. Business phone number ID. |
106540352242922 |
<CARD_BODY_TEXT>String |
Optional. Card body text. Max 160 characters, and up to 2 line breaks. |
*Blue Echeveria*\n\nA rosette-shaped succulent with powdery blue leaves, perfect for brightening up any space. |
<CARD_INDEX>Integer |
Required. Zero-index card index. Cards will appear left to right in scrollable view, starting from 0. |
0 |
<HEADER_TYPE>String |
Required. Header type. Value can be: image - Indicates a card image header. video - Indicates a card video header. See Supported media types. |
image |
<MEDIA_ASSET_URL>String |
Required. Publicly available media asset URL. |
https://www.luckyshrub.com/assets/blue-echeveria.jpeg |
<MESSAGE_BODY_TEXT>String |
Required. Main message body text. Maximum 1024 characters. |
Of course! Here are three of our latest arrivals, each under $25: |
<QUICK_REPLY_BUTTON_ID>String |
Required if using a quick-reply button. Quick-reply button ID. Maximum 256 characters. |
learn-blue-echeveria |
<QUICK_REPLY_BUTTON_LABEL>String |
Required if using a quick-reply button. Quick-reply button label text. Maximum 20 characters. |
Learn more |
<URL_BUTTON_LABEL>String |
Required if using a URL button. URL button label text. Maximum 20 characters. |
Buy now |
<URL_BUTTON_URL>String |
Required if using a URL button. URL to load in the device's default web browser when tapped by the user. |
https://shop.luckyshrub.com/latest/blue-echeveria |
<USER_PHONE_NUMBER>String |
Required. WhatsApp user phone number. |
16505551234 |
Location messages | Developer Documentation
Location messages
Updated: Nov 3, 2025
Location messages allow you to send a location's latitude and longitude coordinates to a WhatsApp user.
Request parameters
| Placeholder | Description | Example Value |
|---|---|---|
<ACCESS_TOKEN>String |
Required.
|
|
<API_VERSION>String |
Optional.
Graph API version. |
v25.0 |
<LOCATION_ADDRESS>String |
Optional.
Location address. |
101 Forest Ave, Palo Alto, CA 94301 |
<LOCATION_LATITUDE>String |
Required.
Location latitude in decimal degrees. |
37.44216251868683 |
<LOCATION_LONGITUDE>String |
Required.
Location longitude in decimal degrees. |
-122.16153582049394 |
<LOCATION_NAME>String |
Optional.
Location name. |
Philz Coffee |
<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>String |
Required.
WhatsApp business phone number ID. |
106540352242922 |
<WHATSAPP_USER_PHONE_NUMBER>String |
Required.
WhatsApp user phone number. |
+16505551234 |
Location request messages | Developer Documentation
Location request messages
Updated: Nov 3, 2025
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 then use to share their location.
Once the user shares their location, a messages webhook is triggered, containing the user's location details.
Request parameters
| Placeholder | Description | Example Value |
|---|---|---|
<ACCESS_TOKEN>String |
Required.
|
|
<API_VERSION>String |
Optional.
Graph API version. |
v25.0 |
<BODY_TEXT>String |
Required.
Message body text. Supports URLs.
Maximum 1024 characters. |
Let's start with your pickup. You can either manually *enter an address* or *share your current location*. |
<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>String |
Required.
WhatsApp business phone number ID. |
106540352242922 |
<WHATSAPP_USER_PHONE_NUMBER>String |
Required.
WhatsApp user phone number. |
+16505551234 |
Webhook syntax
When a WhatsApp user shares their location in response to your message, a messages webhook is triggered containing the user's location details.
Webhook parameters
| Placeholder | Description | Example Value |
|---|---|---|
<LOCATION_ADDRESS>String |
Location address.
This parameter will only appear if the WhatsApp user chooses to share it. |
1071 5th Ave, New York, NY 10128 |
<LOCATION_LATITUDE>Number |
Location latitude in decimal degrees. |
40.782910059774 |
<LOCATION_LONGITUDE>Number |
Location longitude in decimal degrees. |
-73.959075808525 |
<LOCATION_NAME>String |
Location name.
This parameter will only appear if the WhatsApp user chooses to share it. |
Solomon R. Guggenheim Museum |
<TIMESTAMP>String |
UNIX timestamp indicating when our servers processed the WhatsApp user's message. |
1702920965 |
<WHATSAPP_BUSINESS_ACCOUNT_ID>String |
WhatsApp Business Account ID. |
102290129340398 |
<WHATSAPP_BUSINESS_DISPLAY_PHONE_NUMBER>String |
WhatsApp business phone number's display number. |
15550783881 |
<WHATSAPP_BUSINESS_PHONE_NUMBER>String |
WhatsApp business phone number. |
15550783881 |
<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>String |
WhatsApp business phone number ID. |
106540352242922 |
<WHATSAPP_CONTEXT_MESSAGE_ID>String |
WhatsApp message ID of message that the user is responding to. |
wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI1QjJGRjI1RDY0RkE4Nzg4QzcA |
<WHATSAPP_MESSAGE_ID>String |
WhatsApp message ID of the user's message. |
wamid.HBgLMTY0NjcwNDM1OTUVAgASGBQzQTRCRDcwNzgzMTRDNTAwRTgwRQA= |
<WHATSAPP_USER_ID>String |
WhatsApp user's WhatsApp ID. |
16505551234 |
<WHATSAPP_USER_NAME>String |
WhatsApp user's name. |
Pablo Morales |
Reaction messages | Developer Documentation
Reaction messages
Updated: Nov 3, 2025
Reaction messages are emoji-reactions that you can apply to a previous WhatsApp user message that you have received.
Limitations
When sending a reaction message, only a sent message webhook (
status set to sent) will be triggered; delivered and read message webhooks will not be triggered.Request parameters
| Placeholder | Description | Example Value |
|---|---|---|
<ACCESS_TOKEN>String |
Required.
|
|
<API_VERSION>String |
Optional.
Graph API version. |
v25.0 |
<EMOJI>String |
Required.
Unicode escape sequence of the emoji, or the emoji itself, to apply to the user message. |
Unicode escape sequence example:
\uD83D\uDE00Emoji example:
?? |
<WHATSAPP_MESSAGE_ID>String |
Required.
WhatsApp message ID of message you want to apply the emoji to.
If the message you are reacting to is more than 30 days old, doesn't correspond to any message in the chat thread, has been deleted, or is itself a reaction message, the reaction message will not be delivered and you will receive a messages webhook with error code 131009. |
wamid.HBgLMTY0NjcwNDM1OTUVAgASGBQzQUZCMTY0MDc2MUYwNzBDNTY5MAA= |
<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>String |
Required.
WhatsApp business phone number ID. |
106540352242922 |
<WHATSAPP_USER_PHONE_NUMBER>String |
Required.
WhatsApp user phone number. |
+16505551234 |
Template Messages | Developer Documentation
Template Messages
Updated: Nov 4, 2025
Template messages are used to send templates to WhatsApp users. Templates can cover customer care messages, appointment reminders, payment and shipping updates, and much more.
Templates are reusable and can be sent to WhatsApp users outside of a customer service window, however they must be approved before they can be sent in a template message. Templates are also subject to multiple processes that can affect your ability to send them to users, such as quality scores, pausing, and pacing.
Because there’s a lot to know about templates, we have dedicated Templates documentation that explains how to use them effectively.
Text messages | Developer Documentation
Text messages
Updated: Nov 3, 2025
Text messages are messages containing only a text body and an optional link preview.
Link preview
You can have the WhatsApp client attempt to render a preview of the first URL in the body text string, if it contains one. URLs must begin with
http:// or https://. If multiple URLs are in the body text string, only the first URL will be rendered.If omitted, or if unable to retrieve a link preview, a clickable link will be rendered instead.
Video Messages | Developer Documentation
Video Messages
Updated: Nov 3, 2025
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.
Supported Video Formats
Only H.264 video codec and AAC audio codec supported. Single audio stream or no audio stream only.
Note that videos encoded with the H.264 “High” profile and B-frames are not supported by Android WhatsApp clients. We recommend that you use H.264 “Main” profile without B-frames, or the H.264 “Baseline” profile when encoding (or re-encoding with a tool like ffmpeg), and place moov boxes before mdat boxes, for broader compatibility. If you are using ffmpeg, you can use the -movflags faststart flag to place moov boxes before mdata boxes.
| Video Type | Extension | MIME Type | Max Size |
|---|---|---|---|
|
3GPP |
.3gp |
video/3gpp |
16 MB |
|
MP4 Video |
.mp4 |
video/mp4 |
16 MB |
Mark messages as read | Developer Documentation
Mark messages as read
Updated: Nov 3, 2025
When you get a messages webhook indicating an incoming message, you can use the
message.id value to mark the message as read.
It's good practice to mark an incoming messages as read within 30 days of receipt. Marking a message as read will also mark earlier messages in the thread as read.
Request parameters
| Placeholder | Description | Example value |
|---|---|---|
<ACCESS_TOKEN>String |
Required.
|
|
<API_VERSION>String |
Optional.
Graph API version. |
v25.0 |
<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>String |
Required.
WhatsApp business phone number ID. |
106540352242922 |
<WHATSAPP_MESSAGE_ID>String |
Required.
WhatsApp message ID. This ID is assigned to the messages.id property in received message messages webhooks. |
wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBJDQjZCMzlEQUE4OTJBMTE4RTUA |
Contextual replies | Developer Documentation
Contextual replies
Updated: Oct 21, 2025
Contextual replies are a special way of responding to a WhatsApp user message. Sending a message as a contextual reply makes it clearer to the user which message you are replying to by quoting the previous message in a contextual bubble:
Limitations
The contextual bubble will not appear at the top of the delivered message if:
Address Messages | Developer Documentation
Address Messages
Updated: Nov 7, 2025
This feature is only available for 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.Below table outlines the fields that are supported by the address message.
| Field Name | Display Label | Input Type | Supported Countries | Limitations |
|---|---|---|---|---|
name |
Name |
text |
India |
None |
phone_number |
Phone Number |
tel |
India |
Valid phone numbers only |
in_pin_code |
Pin Code |
text |
India |
Max length: 6 |
house_number |
Flat/House Number |
text |
India |
None |
floor_number |
Floor Number |
text |
India |
None |
tower_number |
Tower Number |
text |
India |
None |
building_name |
Building/Apartment Name |
text |
India |
None |
address |
Address |
text |
India |
None |
landmark_area |
Landmark/Area |
text |
India |
None |
city |
City |
text |
India |
None |
state |
State |
text |
India |
None |
Error Handling
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 “India” but has a phone number with an area code of “65”.
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.
Address Message Steps
The steps involved in an Address Message are the following:
Business sends an address message with the action name address_message to the userUser interacts with the message by clicking on the CTA, which brings up an Address Message screen. The user fills out their address and submits the formAfter the address message form is submitted by the user, the partner receives a webhook notification, which contains the details of the address submitted by the user
Sample India Address Message
The following sequence diagram shows a typical integration flow for an address message.
Check Your Response
A successful response includes a
messages object with an ID for the newly created message.An unsuccessful response contains an error message. See Error and Status Codes for more information.
Feature Not Supported
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: