Messages 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: Make sure your messages follow the WhatsApp Business Messaging Policy⁠.Only send messages to WhatsApp users who have opted into receiving messages from your business.Make the messages highly personalized and useful to users.Avoid sending open-ended welcome or introductory messages.Avoid sending customers too many messages a day.Optimize your messages for content and length. 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: Asset link in 1st send message request: 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 All messages except authentication templates: 30 days.Authentication templates: 10 minutes 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. Voice messages require .ogg files encoded with the OPUS codec. If you send a different file type or a file encoded with a different codec, voice message transcription will fail.The play icon will only appear if the file is 512KB or smaller, otherwise it will be replaced with a download icon (a downward facing arrow).The message displays your business’s profile image with a microphone icon.The text transcription appears if the user has enabled Automatic voice message transcripts⁠. If the user has set this to Manual, the text “Transcribe” will appear instead, which will display the transcribed text once tapped. If the user has set voice message transcripts to Never, no text will appear. 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. The download icon will be replaced with a play icon if the WhatsApp user has enabled auto-download⁠ for audio media and conditions for auto-download are met (e.g. connected to wi-fi).If you send a .ogg file encoded with the OPUS code as a basic audio message, the music icon will be replaced with a microphone icon. In addition, if the user has enabled Automatic or Manual voice message transcripts⁠, a text transcription or the text “Transcribe” will accompany the message. Request parameters Placeholder Description Example Value String Required. System token or business token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD String Optional. Graph API version. v25.0 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 String Required if using uploaded media, otherwise omit. ID of the uploaded media asset. 1013859600285441 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 String Required. WhatsApp business phone number ID. 106540352242922 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 String Required. System token or business token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD String Optional. Type of address, such as home or work. Home String Optional. Graph API version. v25.0 String Optional. Contact's birthday. Must be in YYYY-MM-DD format. 1999-01-23 String Optional. City where the contact resides. Menlo Park String Optional. Name of the company where the contact works. Lucky Shrub String Optional. ISO two-letter country code. US String Optional. Country name. United States String Optional. Department within the company. Legal String Optional. Email address of the contact. bjohnson@luckyshrub.com String Optional. Type of email, such as personal or work. Work String Optional. Contact's first name. Barbara String Required. Contact's formatted name. This will appear in the message alongside the profile arrow button. Barbara J. Johnson String Optional. Contact's job title. Lead Counsel String Optional. Contact's last name. Johnson String Optional. Contact's middle name. Joana String Optional. WhatsApp user phone number. +16505559999 String Optional. Type of phone number. For example, cell, mobile, main, iPhone, home, work, etc. Home String Optional. Prefix for the contact's name, such as Mr., Ms., Dr., etc. Dr. String Optional. Two-letter state code. CA String Optional. Street address of the contact. 1 Lucky Shrub Way String Optional. Suffix for the contact's name, if applicable. Esq. String Optional. Type of website. For example, company, work, personal, Facebook Page, Instagram, etc. Company String Optional. Website URL associated with the contact or their company. https://www.luckyshrub.com 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 String Required. WhatsApp business phone number ID. 106540352242922 String Required. WhatsApp user phone number. +16505551234 String Optional. Postal or ZIP code. 94025 Button behavior 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 String Required. System token or business token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD String Optional. Graph API version. v25.0 String Optional. Media asset caption text. Maximum 1024 characters. Lucky Shrub Invoice String Optional. Document filename, with extension. The WhatsApp client will use an appropriate file type icon based on the extension. lucky-shrub-invoice.pdf String Required if using uploaded media, otherwise omit. ID of the uploaded media asset. 1013859600285441 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 String Required. WhatsApp business phone number ID. 106540352242922 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 String Required. System token or business token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD String Optional. Graph API version. v25.0 String Optional. Media asset caption text. Maximum 1024 characters. The best succulent ever? String Required if using uploaded media, otherwise omit. ID of the uploaded media asset. 1013859600285441 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 String Required. WhatsApp business phone number ID. 106540352242922 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 String Required. System token or business token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD String Optional. Graph API version. v25.0 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 String Required. Body text. URLs are automatically hyperlinked. Maximum 1024 characters. Tap the button below to see available dates. String Required. Button label text. Must be unique if using multiple buttons. Maximum 20 characters. See Dates Required. URL to load in the device's default web browser when tapped by the WhatsApp user. https://www.luckyshrub.com?clickID=kqDGWd24Q5TRwoEQTICY7W1JKoXvaZOXWAS7h1P76s0R7Paec4 String Required if using a footer. Footer text. URLs are automatically hyperlinked. Maximum 60 characters. Dates subject to change. String Required if using a text header. Header text. Maximum 60 characters. New workshop dates announced! String Required. WhatsApp business phone number ID. 106540352242922 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 String Required. System token or business token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD String Optional. Graph API version. v25.0 String Required. Button label text. When tapped, reveals rows (options the WhatsApp user can tap). Supports a single button. Maximum 20 characters. Shipping Options String Required. Message body text. Supports URLs. Maximum 4096 characters. Which shipping option do you prefer? String Optional. Message footer text. Maximum 60 characters. Lucky Shrub: Your gateway to succulentsT String Optional. The header object is optional. Supports text header type only. Maximum 60 characters. Choose Shipping Option String Optional. Row description. Maximum 72 characters. Next Day to 2 Days String Required. At least one row is required. Supports up to 10 rows. Maximum 200 characters. priority_express String Required. Row title. At least 1 row is required. Supports up to 10 rows. Maximum 24 characters. Priority Mail Express String Required. Section title text. At least 1 section is required. Supports up to 10 sections. Maximum 24 characters. I want it ASAP! String Required. WhatsApp business phone number ID. 106540352242922 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 Messages must include between 2 and 10 cards.Main message body text is required.Main message headers, footers, and interactive components are not supported.Cards must include either an image or video header. Other header types are not supported.Card body text is optional.Cards must include either one URL button, or one or more quick-reply buttons. Button types and numbers must match across all cards (for example, if you define a card with 2 quick-reply buttons, all cards must define exactly 2 quick-reply buttons). Request parameters Placeholder Description Example value String Required. Access token. EAAJB... String Optional. API version. v23.0 Integer Required. Business phone number ID. 106540352242922 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. Integer Required. Zero-index card index. Cards will appear left to right in scrollable view, starting from 0. 0 String Required. Header type. Value can be: image - Indicates a card image header. video - Indicates a card video header. See Supported media types. image String Required. Publicly available media asset URL. https://www.luckyshrub.com/assets/blue-echeveria.jpeg String Required. Main message body text. Maximum 1024 characters. Of course! Here are three of our latest arrivals, each under $25: String Required if using a quick-reply button. Quick-reply button ID. Maximum 256 characters. learn-blue-echeveria String Required if using a quick-reply button. Quick-reply button label text. Maximum 20 characters. Learn more String Required if using a URL button. URL button label text. Maximum 20 characters. Buy now 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 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 String Required. System token or business token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD String Optional. Graph API version. v25.0 String Optional. Location address. 101 Forest Ave, Palo Alto, CA 94301 String Required. Location latitude in decimal degrees. 37.44216251868683 String Required. Location longitude in decimal degrees. -122.16153582049394 String Optional. Location name. Philz Coffee String Required. WhatsApp business phone number ID. 106540352242922 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 String Required. System token or business token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD String Optional. Graph API version. v25.0 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*. String Required. WhatsApp business phone number ID. 106540352242922 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 String Location address. This parameter will only appear if the WhatsApp user chooses to share it. 1071 5th Ave, New York, NY 10128 Number Location latitude in decimal degrees. 40.782910059774 Number Location longitude in decimal degrees. -73.959075808525 String Location name. This parameter will only appear if the WhatsApp user chooses to share it. Solomon R. Guggenheim Museum String UNIX timestamp indicating when our servers processed the WhatsApp user's message. 1702920965 String WhatsApp Business Account ID. 102290129340398 String WhatsApp business phone number's display number. 15550783881 String WhatsApp business phone number. 15550783881 String WhatsApp business phone number ID. 106540352242922 String WhatsApp message ID of message that the user is responding to. wamid.HBgLMTY0NjcwNDM1OTUVAgARGBI1QjJGRjI1RDY0RkE4Nzg4QzcA String WhatsApp message ID of the user's message. wamid.HBgLMTY0NjcwNDM1OTUVAgASGBQzQTRCRDcwNzgzMTRDNTAwRTgwRQA= String WhatsApp user's WhatsApp ID. 16505551234 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 String Required. System token or business token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD String Optional. Graph API version. v25.0 String Required. Unicode escape sequence of the emoji, or the emoji itself, to apply to the user message. Unicode escape sequence example: \uD83D\uDE00 Emoji example: ?? 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= String Required. WhatsApp business phone number ID. 106540352242922 String Required. WhatsApp user phone number. +16505551234 Template Messages | Developer Documentation Template MessagesUpdated: Nov 4, 2025Template 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 String Required. System token or business token. EAAAN6tcBzAUBOZC82CW7iR2LiaZBwUHS4Y7FDtQxRUPy1PHZClDGZBZCgWdrTisgMjpFKiZAi1FBBQNO2IqZBAzdZAA16lmUs0XgRcCf6z1LLxQCgLXDEpg80d41UZBt1FKJZCqJFcTYXJvSMeHLvOdZwFyZBrV9ZPHZASSqxDZBUZASyFdzjiy2A1sippEsF4DVV5W2IlkOSr2LrMLuYoNMYBy8xQczzOKDOMccqHEZD String Optional. Graph API version. v25.0 String Required. WhatsApp business phone number ID. 106540352242922 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 You cannot send a reaction message as a contextual reply. The contextual bubble will not appear at the top of the delivered message if: The previous message has been deleted or moved to long term storage (messages are typically moved to long term storage after 30 days, unless you have enabled local storage).You reply with an audio, image, or video message and the WhatsApp user is running KaiOS.You use the WhatsApp client to reply with a push-to-talk? message and the WhatsApp user is running KaiOS.You reply with a template message. 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: