This chapter of our API Documentation is designed for customers who have been granted access to WhatsApp Business API. It is important that you request access to this program via our Channels portal. Without this approval you can not make use of this part of the API.
WhatsApp also comes with a considerable set of 'business rules' that you might have to take into account when using WhatsApp. You can find these in the WhatsApp Business Policy and the WhatsApp Commerce Policy
Note
since WhatsApp for Business is used for 2-way communication (chat) it is important to also implement the Inbound flow using our API documentation of the incoming messages.
Fact sheet
| Feature | Support | Remarks |
|---|---|---|
| Text messages | Yes | The maximum length of a WhatsApp message is 4096 characters and it must be UTF-8 encoded. |
| Media | Yes | Media name attribute should end in the proper file extension. Only one media file is allowed per message. When the linked media doesn't exist/can't be found, the message will not be sent at all. The text message, if provided, is sent in a separate Instagram message. |
| Media: images | Yes | Maximum file size for an uploaded image is 5 MB. Supported formats: png, jpeg. |
| Media: audio | Yes | Maximum file size for an uploaded audio file is 16 MB. Supported formats: ACC, M4A, MP3, AMR, OGG-OPUS. |
| Media: video | Yes | Maximum file size for an uploaded video file is 16 MB. Supported formats: mpeg4. |
| Media: document | Yes | Maximum file size for an uploaded document file is 100 MB. Supported formats: plaintext, PDF, MS Word, MS PowerPoint, MS Excel. |
| Interactive messages | Yes | Send List, Reply buttons, call-to-action (CTA) URL button or Location request messages. List messages can contain 10 options. Reply buttons messages can contain a maximum of 13 reply buttons. Call-to-action URL button messages can contain 1 call-to-action URL button. |
| Location messages | Yes | |
| Contact messages | Yes | Send one or more contacts. |
| Catalog messages | Yes | Message containing your entire product catalog. |
| Product messages | Yes | Messages containing a selection of up to 30 items from a business’ inventory. |
| Template messages | Yes | Available templates: Media and interactive. |
Message encryption
When making use of the WhatsApp Business API solution, messages are encrypted on our platform. In our WhatsApp implementation guide we explain how this works. Encryption is a mandatory WhatsApp feature, implemented by CM.com. You don't have to do anything to enable this, it is part of the the WhatsApp account creation.
Rate limits
There are two types of rate limits for WhatsApp. Capacity limits and messaging limits.
Capacity limit is restriction in maximum throughput, that allows 50 messages per second. When you are sending more than this maximum throughput, messages may fail from being sent.
Messaging limit is a restriction in how many unique users your business can send messages to on a daily basis. More about this can be read here: Messaging Limits
Sending WhatsApp messages
For service requests, users usually initiate a conversation and will reach out to you. To link incoming messages to your outbound messages, the phone number field is used (to --> number and from fields). When sending a WhatsApp message it is important to add WhatsApp as a value to the allowedChannels field.
If you have configured multiple WhatsApp-numbers in our platform, you can use the desired phone number by providing it in the from field. If this does not match to one of your phone numbers, your first onboarded number will be used.
The body's content attribute is also required. It is the content value that will be used when falling back to SMS as a delivery channel. The body.content attribute needs to be backwards compatible with SMS channel requirements. This means it is affected by maximum size limitations of SMS as described in the section on SMS multipart messaging.
Note
The WhatsApp protocol strives for, but does not guarantee, in-order delivery of your messages.
Message example
This example makes use of the Rich Content conversation array, with 3 conversation items (or speech bubbles), 2 text bubbles and one image. These will all be delivered at once.
{
"messages": {
"authentication": {
"productToken": "your product token"
},
"msg": [{
"body": {
"type": "auto",
"content": "Fallback Text for SMS"
},
"to": [{
"number": "00316012345678"
}],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [{
"text": "A text message with *bold* formatting in a speech bubble."
}, {
"text": "Another speech bubble"
}, {
"media": {
"mediaName": "and an image",
"mediaUri": "https://www.cm.com/cdn/web/nl-nl/blog/conversational-commerce.jpg",
"mimeType": "image/jpeg"
}
}]
}
}]
}
}
Text messages
Text messages are and should always be encoded in UTF-8 and do support characters like emojis 😀. This is true for both the body field and when using a text item inside a Rich Content conversation. Please remember that emoji rendering is device dependent and older devices therefore may not support the newest unicode emojis and depending on the font used by the device, an emoji may look slightly different on from one device to another 📱💻🖥.
The maximum length of a WhatsApp text message bubble is 4096 characters.
WhatsApp specifically allows a limited amount of formatting for text messages that you can make use of. These markup characters need to be prefixed with a space character in order for them to take effect.
| Formatting | Symbol | Example |
|---|---|---|
| Bold | Asterisk (*) | Your total is *$10.50*. |
| Italics | Underscore (_) | Welcome to _WhatsApp_! |
| Tilde (~) | This is ~better~ best! | |
Code | Three backticks (`````) | ```print 'Hello World';``` |
| A line break | \n | Hello \n World |
Text message
The example below will send a simple text-only WhatsApp message.
{
"messages": {
"authentication": {
"productToken": "your product token"
},
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"text": "CM.com - Be part of it."
}
]
}
}
]
}
}
URL preview messages
Any URLs present in the message text of a WhatsApp message will be automatically recognized by the clients as links. Additionally, the first URL encountered in a text message will generate a URL preview. For this it is required that the URL starts with http:// or https://
A URL preview can contain a title, a message and a small fragment of text. These elements are automatically retrieved from the destination website. To support this preview, the destination website needs to have implemented the Open Graph Protocol.
The URL preview is retrieved by the WhatsApp software running on the CM.com side, before being sent to the client. This is for privacy reasons.
Text with url preview message
The example below will send a simple text/URL WhatsApp message.
{
"messages": {
"authentication": {
"productToken": "your product token"
},
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"text": "https://CM.com - Be part of it."
}
]
}
}
]
}
}
Media messages
In WhatsApp the following media types are supported:
| Type | Supported file types | Max. size | Content-Type |
|---|---|---|---|
| image |
| 5 MB |
|
| video |
| 16 MB |
|
| audio |
| 16 MB |
|
| document |
| 100 MB |
|
Notes:
- File uploads should not be larger than the specified maximum file size.
- For video, only H.264 video codec and AAC audio codec is supported.
- Video files are required to have an audio track.
- Voice messages, gif animations, and stickers are not supported.
- The file should be hosted on a publicly accessible URI using port 80 (HTTP) or 443 (HTTPS).
- The file must be served with the correct Content-Type header.
As data usage costs might apply when the end user is not on Wifi, please be considerate when sending media messages. We strongly advise not to send files larger than 1 MB, and for a conversation not to exceed 20Mb.
Media object contains the following fields:
| Term | Description |
|---|---|
| MediaName | The filename for a document, or the caption of the image or video (not supported for audio). |
| MediaUri | The location of the image, audio, or video. |
| MimeType | The mime type of the image, audio, or video. |
Media message containing an image
In the example below, we send an image message that contains both text and an image. The media name will be used as text.
{
"messages": {
"authentication": {
"productToken": "your-product-token"
},
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"media": {
"mediaName": "CM.com and the WhatsApp Business Platform",
"mediaUri": "https://www.cm.com/cdn/web/logo/whatsapp-business-platform-download-logo.jpg",
"mimeType": "image/jpeg"
}
}
]
}
}
]
}
}
Media message containing a video.
In the example below, we send a video message that contains both text and a video. The media name will be used as text.
{
"messages": {
"authentication": {
"productToken": "your-product-token"
},
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"media": {
"mediaName": "CM.com - Be part of it.",
"mediaUri": "https://your-company.com/your-video.mp4",
"mimeType": "video/mp4"
}
}
]
}
}
]
}
}
In the example below, we send an audio message.
{
"messages": {
"authentication": {
"productToken": "your-product-token"
},
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"media": {
"mediaUri": "https://your-company.com/your-audio.mp3",
"mimeType": "audio/mpeg"
}
}
]
}
}
]
}
}
In the example below, we send a document message.
{
"messages": {
"authentication": {
"productToken": "your-product-token"
},
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"media": {
"mediaName": "CM.com - Be part of it.",
"mediaUri": "https://your-company.com/your-document.pdf",
"mimeType": "application/pdf"
}
}
]
}
}
]
}
}
Interactive messages
Interactive messages is a WhatsApp feature that offers enhanced functionality for messages. The available options include:
- List Messages: Facilitate user choices by sending list pickers that present a menu of up to 10 options.
- Reply Buttons: Streamline conversation flow by incorporating reply buttons in your messages. Note that a maximum of three reply buttons can be included in a single message.
- Call-to-action URL Button: Customers may be hesitant to tap raw URLs containing lengthy or obscure strings in text messages. In these situations, sending an interactive message with body text and a call-to-action (CTA) URL button might be an option.
- Location Request messages: Location request messages allows you to send messages with text along with a 'Send Location' button. Upon tapping the button, a location sharing screen will appear, enabling users to easily share their location.
Please note the following guidelines for the header object
- It is possible to add images, videos or documents to the header of a interactive message, but only when using the interactive reply buttons message. To do so add an media object in the Interactive Header. Audio is not supported.
- You also need to update the header type to the type of media you are sending. The options are image, video or document.
Interactive list message
Interactive list message
Please note the following guidelines
- The title of your section contains an maximum length: 24 characters.
- Each row must have a title (Maximum length: 24 characters) and an ID (Maximum length: 200 characters).
- You can add a description (Maximum length: 72 characters), but it is optional.
In the example below, we send a interactive list message that contains list two items.
{
"messages": {
"authentication": {
"productToken": "your-product-token"
},
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"interactive": {
"type": "list",
"header": {
"type": "text",
"text": "your-header-content"
},
"body": {
"text": "your-text-message-content"
},
"footer": {
"text": "your-footer-content"
},
"action": {
"button": "cta-button-content",
"sections": [
{
"title": "your-section-title1",
"rows": [
{
"id": "unique-row-identifier1",
"title": "row-title-content",
"description": "row-description-content"
}
]
},
{
"title": "your-section-title2",
"rows": [
{
"id": "unique-row-identifier2",
"title": "row-title-content",
"description": "row-description-content"
}
]
}
]
}
}
}
]
}
}
]
}
}
Interactive reply button message
Interactive reply button message
Please note the following guidelines
- title: Button title. It cannot be an empty string and must be unique within the message. Does not allow emojis or markdown. Maximum length: 20 characters.
- id: Unique identifier for your button. This ID is returned in the webhook when the button is clicked by the user. Maximum length: 256 characters.
In the example below, we send a interactive reply button message that contains two reply buttons.
{
"messages": {
"authentication": {
"productToken": "your-product-token"
},
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"interactive": {
"type": "button",
"header": {
"type": "text",
"text": "your text"
},
"body": {
"text": "your-text-body-content"
},
"footer": {
"text": "your-text-footer-content"
},
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"id": "unique-postback-id1",
"title": "First Button"
}
},
{
"type": "reply",
"reply": {
"id": "unique-postback-id2",
"title": "Second Button"
}
}
]
}
}
}
]
}
}
]
}
}
Interactive reply button message with image (media)
Interactive reply button message with image
In the example below, we send a interactive reply button message with an image header and that contains two reply buttons. (Other supported media types for the header are: video and document)
{
"messages": {
"authentication": {
"productToken": "your-product-token"
},
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"interactive": {
"type": "button",
"header": {
"type": "image",
"media": {
"mediaName": "CM.com - Be part of it.",
"mediaUri": "https://www.cm.com/cdn/web/blog/content/logo-cmcom.png",
"mimeType": "image/jpeg"
}
},
"body": {
"text": "your-text-body-content"
},
"footer": {
"text": "your-text-footer-content"
},
"action": {
"buttons": [
{
"type": "reply",
"reply": {
"id": "unique-postback-id1",
"title": "First Button"
}
},
{
"type": "reply",
"reply": {
"id": "unique-postback-id2",
"title": "Second Button"
}
}
]
}
}
}
]
}
}
]
}
}
Interactive CTA button message
Interactive CTA button message
Please note the following guidelines
Only a single URL button is supported by WhatsApp in a call-to-action URL button message. If multiple CTA buttons are supplied, only the first one will be sent with the call-to-action URL button message.
In the example below, we send a call-to-action URL button message.
{
"messages": {
"authentication": {
"productToken": "your-product-token"
},
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"interactive": {
"type": "button",
"header": {
"type": "text",
"text": "your text"
},
"body": {
"text": "your-text-body-content"
},
"footer": {
"text": "your-text-footer-content"
},
"action": {
"buttons": [
{
"type": "openurl",
"id": "unique-postback-id",
"title": "Button",
"url": "your url"
}
]
}
}
}
]
}
}
]
}
}
Location Request messages
Location request messages allows you to send messages with text along with a 'Send Location' button. Upon tapping the button, a location sharing screen will appear, enabling users to easily share their location.
Location Request message
In the example below, we send a Location Request message.
{
"messages": {
"authentication": {
"productToken": "your-product-token"
},
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": [
"WhatsApp"
],
"richContent": {
"conversation": [
{
"interactive": {
"type": "location_request_message",
"body": {
"text": "Hello! Please share your pickup location so we can send you a cab."
},
"action": {
"name": "send_location"
}
}
}
]
}
}
]
}
}
Interactive message (Flows)
In the example below, we send a WhatsApp Flows button message.
{
"messages": {
"authentication": {
"productToken": "your-product-token"
},
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": [
"WhatsApp"
],
"richContent": {
"conversation": [
{
"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": "your-flow-token",
"flow_id": "your-flow-id",
"flow_cta": "Button title!",
"flow_action": "navigate",
"flow_action_payload": {
"screen": "your-flow-id",
"data": {
"options-field": "optional-value"
}
}
}
}
}
}
]
}
}
]
}
}
Location messages
To send a location message to a user use the location object, which contains the following fields:
| Field | Remarks |
|---|---|
| Latitude | The latitude in degrees |
| Longitude | The longitude in degrees |
| SearchQuery | The address to display |
| Label | The label to display at the pin |
Location message
In the example below, we send a location message.
{
"messages": {
"authentication": {
"productToken": "your-product-token"
},
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"location": {
"latitude": "51.603802",
"longitude": "4.770821",
"label": "CM HQ",
"searchQuery": "Konijnenberg 30"
}
}
]
}
}
]
}
}
Contact messages
To send one or more contacts to a user use the Contacts array. The contacts array can contain the following informative objects:
| Field | Required |
|---|---|
| name | Yes |
| emails | No |
| addresses | No |
| org | No |
| phones | No |
| urls | No |
| birthday | No |
Important
Note that the
name.formatted_nameand at least one of:name.first_name, name.last_name, name.middle_name, name.suffix, name.prefixis required.
Contact message
In the example below, we send a contact message.
{
"messages": {
"authentication": {
"productToken": "your-product-token"
},
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"contacts": [
{
"name": {
"first_name": "CM.com",
"formatted_name": "CM.com HQ",
"last_name": "HQ"
},
"addresses": [
{
"city": "Breda",
"country": "Netherlands",
"country_code": "NL",
"street": "Konijnenberg 30",
"type": "WORK",
"zip": "4825 BD"
}
],
"emails": [
{
"email": "[email protected]",
"type": "WORK"
}
],
"org": {
"company": "CM.com",
"department": "Development",
"title": "Developer"
},
"phones": [
{
"phone": "1234567890",
"type": "WORK"
}
],
"urls": [
{
"url": "https://www.cm.com",
"type": "WORK"
}
],
"birthday": "2000-01-01"
}
]
}
]
}
}
]
}
}
Catalog message
Catalog messages are messages that allow you to showcase your entire product catalog within WhatsApp. When a user taps the View catalog button, your product catalog appears within WhatsApp.
Catalog message
In the example below, we send a catalog message.
{
"messages": {
"authentication": {
"productToken": "your-product-token"
},
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "0031612345678"
}
],
"from": "0031687654321",
"allowedChannels": [
"WhatsApp"
],
"richContent": {
"conversation": [
{
"interactive": {
"type": "catalog_message",
"body": {
"text": "Check our product catalog!"
},
"footer": {
"text": "Enjoy nice products!"
},
"action": {
"name": "catalog_message"
}
}
}
]
}
}
]
}
}
Product messages
WhatsApp Product Messages let you easily share products with your customers. There are two options:
- Product List Messages: These messages include a selection of up to 30 items from a business's inventory.
- Single Product Messages: These messages showcase a single product item from the business's inventory, presented in a Product Detail Page (PDP) format.
When your customers receive these product messages, they can add items to a shopping cart, send the cart to your business, and share products with their contacts on WhatsApp.
Keep in mind that to send these messages, you need to link a WhatsApp Business number to a corresponding Facebook Business page. Also, make sure to add your products to a catalog using the Commerce Manager for effective distribution of product messages. For more details about product catalogs, visit WhatsApp commerce guide.
Single product message
In the example below, we send a single product message.
{
"messages": {
"authentication": {
"productToken": "your-product-token"
},
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"interactive": {
"type": "product",
"body": {
"text": "Do you want to enjoy the fun of a new mousepad?"
},
"footer": {
"text": "Limited edition, only 1 per order."
},
"action": {
"catalog_id": "catalog-id",
"product_retailer_id": "product-id-in-catalog"
}
}
}
]
}
}
]
}
}
Product list message
In the example below, we send a product list message.
{
"messages": {
"authentication": {
"productToken": "your-product-token"
},
"msg": [
{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [
{
"number": "00316012345678"
}
],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"interactive": {
"type": "product_list",
"body": {
"text": "Hi customer! We have some new products in stock!"
},
"header": {
"type": "text",
"text": "New products"
},
"action": {
"catalog_id": "catalogid-from-commercemanager",
"sections": [
{
"title": "Products",
"product_items": [
{
"product_retailer_id": "product-id-in-catalog"
},
{
"product_retailer_id": "product-id-in-catalog"
},
{
"product_retailer_id": "product-id-in-catalog"
}
]
}
]
}
}
}
]
}
}
]
}
}
Remarks
Currently, these types of messages can be received in the following minimum WhatsApp versions:
iOS: 2.21.100 (Multi-Product Messages) and 2.21.210 (Single Product Messages).
Android: 2.21.9.15 (Multi-Product Messages) and 2.21.19 (Single Product Messages).
Web: The web client that supports these features has been launched.
Template messages
To send a message to a user first a template must be used. These templates must be setup and approved before they can be used. You can request templates via the Channels portal.
Once a template is approved you can use the template namespace and name to send a message (Use the details button in your template overview to find these values).
The template message must have the exact same number of variables as the template has. The same template can be set-up in multiple languages, hence you also need a language parameter.
Please remember that a user must have opted in for the type of communication as well. The opt-in must be an active opt-in. This means it must be triggered by a user action, such as entering a phone number in a WhatsApp field or checking a box to indicate consent.
Requirements for Opt-In:
You are obligated to adhere to the following criteria when securing opt-ins:
- Clearly communicate that users are opting in to receive messages from you via WhatsApp.
- Explicitly mention your name for which users are opting in to receive messages.
- Ensure compliance with relevant laws and regulations.
Approved Opt-In Methods:
Any opt-in method must align with the aforementioned requirements to be considered policy compliant. The following are examples of acceptable opt-in methods:
- SMS
- Website
- Within a WhatsApp thread
- Over the phone (utilizing an interactive voice response (IVR) flow)
- In-person or via paper (allowing users to physically sign a document to opt in)
You must persist in enhancing the user experience during the opt-in process. To achieve this, you should:
- Establish clear expectations for users regarding the messages they will receive. This involves obtaining opt-ins that cover various message categories (e.g., order updates, relevant offers, product recommendations) or obtaining separate opt-ins for specific message categories. This approach reduces the risk of users blocking you due to unsolicited messages.
- Provide explicit instructions on how users can opt out of receiving messages from specific categories and ensure compliance with these requests.
- Design opt-in and opt-out processes that are transparent and user-friendly.
- Clearly articulate the value of receiving information via WhatsApp.
- Vigilantly monitor the quality rating, especially when introducing new opt-in methods.
Important
It is strongly advised that you prioritize user experience optimization when designing opt-in processes.
Users can block or report businesses and Meta will rate limit businesses if the business's quality is low for a sustained period of time.
A template object contains a 'whatsapp' object, which corresponds to the template object in the WhatsApp for Business docs.
| Field | Description | Required |
|---|---|---|
| namespace | The namespace that will be used. Will be provided to you after the template is approved | Yes |
| element_name | The element name of the template that will be used. Will be provided to you after the template is approved | Yes |
| language | Specifies the language, see below for object definition | Yes |
| components | Array containing the content-components of the message, to personalize the templated message. See the WhatsApp documentation for advanced details. | Yes (only for media templates) |
| localizable_params | An array of parameters to personalize the templated message. Use components if your template needs media or has a header/footer. See the WhatsApp documentation for advanced details. | Yes (only for regular templates) |
Note
Only PDF documents are supported for media-based message templates.
Media template message
Media templates is a newer generation of WhatsApp templates, which in addition to the text body, can also feature a header with an additional image, video or document, as well as a footer.
The header can have three component types: image, document, video and text. The body and footer can only have the component type text. The parameters are similar to the localizable_params of the older template format, but NOT the same.
In the example below, we send a media template message.
{
"messages": {
"authentication": {
"producttoken": "your product token"
},
"msg": [
{
"from": "00316098765432",
"to": [
{
"number": "0031612345678"
}
],
"body": {
"type": "auto",
"content": "This is a WhatsApp message"
},
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"template": {
"whatsapp": {
"namespace": "your namespace id here",
"element_name": "TEMPLATE_NAME",
"language": {
"policy": "deterministic",
"code": "en"
},
"components": [
{
"type": "header",
"parameters": [
{
"type": "image",
"media": {
"mediaName": "conversational-commerce",
"mediaUri": "https://www.cm.com/cdn/web/nl-nl/blog/conversational-commerce.jpg",
"mimeType": "image/jpeg"
}
}
]
},
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "replace-value-1"
},
{
"type": "currency",
"currency": {
"fallback_value": "$100.99",
"code": "USD",
"amount_1000": 100990
}
},
{
"type": "date_time",
"date_time": {
"fallback_value": "February 25, 1977",
"day_of_week": 5,
"day_of_month": 25,
"year": 1977,
"month": 2,
"hour": 15,
"minute": 33, // OR
"timestamp": 1485470276
}
}
]
}
]
}
}
}
]
}
}
]
}
}
Interactive template message
Interactive templates is a newer generation of WhatsApp templates, which in addition to the media template, can also support button-components.
The button-component can be either of sub_type: quick_reply or url.
- With
quick_replythe end-user will see a suggestion to respond with. The button text itself has to be specified during creation of the template. - With
urlyou are able to send a Call-to-action button. This can be a phone number to call, or an url to visit. This has to be specified during creation of the template as well.
The payload on quick_reply buttons will be sent back when an end-user interacts with such a button. The maximum length of the payload is 128 characters. This will be explained in the incoming messages documentation.
In the example below, we send an interactive template message.
{
"messages": {
"authentication": {
"producttoken": "your product token"
},
"msg": [
{
"from": "00316098765432",
"to": [
{
"number": "00316012345678"
}
],
"body": {
"type": "auto",
"content": "fallback message"
},
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"template": {
"whatsapp": {
"namespace": "your namespace id here",
"element_name": "TEMPLATE_NAME",
"language": {
"policy": "deterministic",
"code": "en"
},
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "your-text-string"
}
]
},
{
"type": "button",
"sub_type": "quick_reply",
"index": "0",
"parameters": [
{
"type": "payload",
// Business Developer-defined payload
"payload": "aGlV0RT"
}
]
},
{
"type": "button",
"sub_type": "url",
"index": "1",
"parameters": [
{
"type": "text",
// Business Developer-defined dynamic URL suffix
"text": "9rwn"
}
]
},
{
"type": "button",
"sub_type": "url",
"index": "2",
"parameters": [
{
"type": "text",
// Business Developer-defined dynamic URL suffix
"text": "ticket.pdf"
}
]
}
]
}
}
}
]
}
}
]
}
}
Template message (Regular)
This is the template message format without media. There are some rules that must be adhered to:
| Field | Description | Required |
|---|---|---|
| currency | If the currency object is used, it must contain required parameters currency_code and amount_1000 | No |
| date_time | If the date_time object is used, further definition of the date and time is required. See the example below for two of the options | No |
The currency object:
| Field | Description | Required |
|---|---|---|
| fallback_value | Default text if localization fails. All of the localization parameters must have a fallback value. When specifying text, just the fallback value is required | Yes |
| code | Currency code as defined in ISO 4217 | Yes |
| amount_1000 | Amount multiplied by 1000 | Yes |
The date_time object:
| Field | Description | Required |
|---|---|---|
| fallback_value | Default text if localization fails. All of the localization parameters must have a fallback value. When specifying text, just the fallback value is required | Yes |
| day_of_week | If different from the value derived from the date (if specified), use the derived value. Both strings and numbers are accepted. Options: "MONDAY", 1, "TUESDAY", 2, "WEDNESDAY", 3, "THURSDAY", 4, "FRIDAY", 5, "SATURDAY", 6, "SUNDAY", 7 | No |
| year | The year | No |
| month | The month | No |
| day_of_month | The day of month | No |
| hour | The hour | No |
| minute | The minute | No |
| calendar | Type of calendar. Options: GREGORIAN, SOLAR_HIJRI | No |
Note
The hsm-templates that use the
localizable_params-structure, will be deprecated in a future version.
In the example below, we send a template message.
{
"messages": {
"authentication": {
"producttoken": "your product token"
},
"msg": [
{
"from": "00316098765432",
"to": [
{
"number": "0031612345678"
}
],
"body": {
"type": "auto",
"content": "This is a WhatsApp message"
},
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [
{
"template": {
"whatsapp": {
"namespace": "your namespace id here",
"element_name": "TEMPLATE_NAME",
"language": {
"policy": "deterministic",
"code": "en"
},
"components": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "your-text-string"
},
{
"type": "currency",
"currency": {
"fallback_value": "$100.99",
"code": "USD",
"amount_1000": 100990
}
},
{
"type": "date_time",
"date_time": {
"fallback_value": "February 25, 1977",
"day_of_week": 5,
"day_of_month": 25,
"year": 1977,
"month": 2,
"hour": 15,
"minute": 33
}
},
{
"type": "date_time",
"date_time": {
"fallback_value": "February 25, 1977",
"timestamp": 1485470276
}
}
]
}
]
}
}
}
]
}
}
]
}
}
Template message (Flows)
In the example below, we send an interactive WhatsApp Flows message.
{
"messages": {
"authentication": {
"producttoken": "your product token"
},
"msg": [
{
"from": "00316098765432",
"to": [
{
"number": "00316012345678"
}
],
"body": {
"type": "auto",
"content": "fallback message"
},
"allowedChannels": [
"WhatsApp"
],
"richContent": {
"conversation": [
{
"template": {
"whatsapp": {
"namespace": "your-namespace",
"element_name": "your-template-name",
"language": {
"policy": "deterministic",
"code": "en"
},
"components": [
{
"type": "button",
"sub_type": "flow",
"index": "0",
"parameters": [
{
"type": "action",
"action": {
"flow_token": "your-flow-token",
"flow_action_data": {}
}
}
]
}
]
}
}
}
]
}
}
]
}
}
Template message (Carousel)
In the example below, we send an interactive WhatsApp Carousel message.
{
"messages": {
"authentication": {
"producttoken": "your product token"
},
"msg": [
{
"from": "00316098765432",
"to": [
{
"number": "00316012345678"
}
],
"body": {
"type": "auto",
"content": "fallback message"
},
"allowedChannels": [
"WhatsApp"
],
"richContent": {
"conversation": [
{
"template": {
"whatsapp": {
"namespace": "your-namespace",
"element_name": "your-template-name",
"language": {
"policy": "deterministic",
"code": "en"
},
"components": [
{
"type": "BODY",
"parameters": []
},
{
"type": "CAROUSEL",
"cards": [
{
"card_index": 0,
"components": [
{
"type": "HEADER",
"parameters": [
{
"type": "IMAGE",
"image": {
"mediaUri": "https://cmcom.s3.eu-west-3.amazonaws.com/webimage-C0D8E5EE-2ABC-41F2-B3E694BF22A1D6C6.png"
}
}
]
},
{
"type": "BODY",
"parameters": []
},
{
"type": "BUTTON",
"sub_type": "QUICK_REPLY",
"index": 0,
"parameters": [
{
"type": "PAYLOAD",
"payload": "your-payload-here"
}
]
}
]
},
{
"card_index": 1,
"components": [
{
"type": "HEADER",
"parameters": [
{
"type": "IMAGE",
"image": {
"mediaUri": "https://cmcom.s3.eu-west-3.amazonaws.com/webimage-4C0C8462-0F93-41AC-A66F3D614E53DFA5.png"
}
}
]
},
{
"type": "BODY",
"parameters": []
},
{
"type": "BUTTON",
"sub_type": "QUICK_REPLY",
"index": 0,
"parameters": [
{
"type": "PAYLOAD",
"payload": "your-payload-here"
}
]
}
]
}
]
}
]
}
}
}
]
}
}
]
}
}
Template message (Limited-time offer and Coupon code)
Limited-time offer templates let you show expiration dates and countdown timers for offer codes in your messages. It makes it easy for you to let end-users know about time-limited deals and keep them engaged. Coupon code templates are marketing templates that display a single copy code button that can be combined with a URL button. When tapped, the code is copied to the end-users clipboard. They can also contain an image as header.
Limited-time offer template message
Limited-time offer object:
| Field | Description | Required |
|---|---|---|
| expiration_time_ms | Offer code expiration time as a UNIX timestamp in milliseconds. | Yes |
Coupon code:
| Field | Description | Required |
|---|---|---|
| coupon_code | Offer code as text. Maximum 15 characters. | Yes |
In the example below, we send a Limited-time offer template message:
{
"messages": {
"authentication": {
"producttoken": "your product token"
},
"msg": [
{
"from": "00316098765432",
"to": [
{
"number": "00316012345678"
}
],
"body": {
"type": "auto",
"content": "fallback message"
},
"allowedChannels": [
"WhatsApp"
],
"richContent": {
"conversation": [
{
"template": {
"whatsapp": {
"namespace": "your-namespace",
"element_name": "your-template-name",
"language": {
"policy": "deterministic",
"code": "en_US"
},
"components": [
{
"parameters": [],
"type": "body"
},
{
"type": "limited_time_offer",
"parameters": [
{
"type": "limited_time_offer",
"limited_time_offer": {
"expiration_time_ms": 1708184832000
}
}
]
},
{
"type": "button",
"sub_type": "copy_code",
"index": 0,
"parameters": [
{
"type": "coupon_code",
"coupon_code": "1234ab"
}
]
}
]
}
}
}
]
}
}
]
}
}
Coupon code templates are marketing templates that display a copy code button (without expiration date). When tapped, the code is copied to the customer's clipboard. They can also contain an image as header.
Coupon code template message
Coupon code:
| Field | Description | Required |
|---|---|---|
| coupon_code | Offer code as text. Maximum 15 characters. | Yes |
In the example below, we send a Coupon template message:
{
"messages": {
"authentication": {
"producttoken": "your product token"
},
"msg": [
{
"from": "00316098765432",
"to": [
{
"number": "00316012345678"
}
],
"body": {
"type": "auto",
"content": "fallback message"
},
"allowedChannels": [
"WhatsApp"
],
"richContent": {
"conversation": [
{
"template": {
"whatsapp": {
"namespace": "your-namespace",
"element_name": "your-template-name",
"language": {
"policy": "deterministic",
"code": "en_US"
},
"components": [
{
"parameters": [],
"type": "body"
},
{
"type": "button",
"sub_type": "copy_code",
"index": 0,
"parameters": [
{
"type": "coupon_code",
"coupon_code": "1234ab"
}
]
}
]
}
}
}
]
}
}
]
}
}
Important for LTO and Coupon templates
- Only templates categorized as MARKETING are supported.
- Only one copy coupon button per template.
- Footer components are not supported.
- End-users who view a limited-time offer template message using that WhatsApp web app or desktop app will not see the offer, but will instead see a message indicating that they have received a message but that it's not supported in the client they are using.
Language
| Field | Description | Required |
|---|---|---|
| policy | deterministic — Deliver the message template in exactly the language and locale asked for. | Yes |
| code | The code of the language or locale to use — Accepts both language and language_locale formats (e.g., en and en_US). | Yes |
WhatsApp maintains a list of valid language codes
Updated 28 days ago