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.
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 a WhatsApp message
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.
Message example
An example of sending a message via WhatsApp by specifying allowedChannels with a WhatsApp value. 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.
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.
{
"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"
}
}]
}
}]
}
}
Note
The WhatsApp protocol strives for, but does not guarantee, in-order delivery of your messages.
Multiple WhatsApp numbers
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.
Example:
{
"messages": {
"authentication": {
"productToken": "your product token"
},
"msg": [{
"body": {
"type": "auto",
"content": "Message Text"
},
"to": [{
"number": "00316012345678"
}],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"]
}]
}
}
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 can be inserted by using: \n
Message example
{
"messages": {
"authentication": {
"productToken": "your product token"
},
"msg": [{
"body": {
"type": "auto",
"content": "Fallback Text"
},
"to": [{
"number": "00316012345678"
}],
"from": "00316098765432",
"allowedChannels": ["WhatsApp"],
"richContent": {
"conversation": [{
"text": "A text message with *bold* formatting in a speech bubble."
}, {
"text": "Another speech bubble"
}]
}
}]
}
}
URL previews
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.
Template
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.
See also Facebook's opt-in guide.
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) |
Notes:
- Only PDF documents are supported for media-based message templates.
Example 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.
See the WhatsApp documentation for advanced details.
{
"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
}
},
]
}
]
}
}
}]
}
}]
}
}
Example 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. This will be explained in the incoming messages documentation.
See the WhatsApp documentation for advanced details.
{
"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":"aGlzIHRoaXMgaXMgY29vZHNhc2phZHdpcXdlMGZoIGFTIEZISUQgV1FEV0RT"
}
]
},
{
"type": "button",
"sub_type" : "url",
"index": "1",
"parameters": [
{
"type": "text",
// Business Developer-defined dynamic URL suffix
"text": "9rwnB8RbYmPF5t2Mn09x4h"
}
]
},
{
"type": "button",
"sub_type" : "url",
"index": "2",
"parameters": [
{
"type": "text",
// Business Developer-defined dynamic URL suffix
"text": "ticket.pdf"
}
]
}]
}
}
}]
}
}]
}
}
Example template message
This is the template message format without media.
See also the WhatsApp documentation for advanced details.
Note
The hsm-templates that use the
localizable_params-structure, will be deprecated in a future version.
{
"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
}
}
]
}]
}
}
}]
}
}]
}
}
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
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.
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. |
{
"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"
}
}
]
}
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.
Interactive messages
Interactive messages are new features supported by WhatsApp.
The options are:
List Messages: You are now able to send list pickers, if you would like your end user to make an choice you can send messages including a menu of up to 10 options. This will give a much better experience for your end users.
Reply Buttons: Send messages with reply buttons, these type of messages makes the conversation flow much quicker.
You can only send an maximum of 3 reply buttons.
Reply buttons have the same user experience as interactive templates with buttons.
Example list message
{
"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"
}]
}
]
}
}
}]
}
Please note that 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.
Example reply buttons
{
"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"
}
}
]
}
}
}
]
}
Please note of 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.
Example reply buttons with Media
Notes:
It is possible to send images, videos or documents when using reply buttons.
Audio is not supported in combination with actions.
To do so add an media object in the Interactive Header.
You also need to update the header type to what kind of media,
the options are image, video or document.
example:
{
"conversation": [
{
"interactive": {
"type": "button",
"header": {
"type": "image",
"Media": {
"mediaName": "conversational-commerce",
"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"
}
}
]
}
}
}
]
}
Product messages
WhatsApp product messages is an feature to share products with your customers.
Product List Messages: Messages containing a selection of up to 30 items from a business’ inventory.
Single Product Messages: Messages with a single product item from the business’ inventory. The product is displayed in a Product Detail Page (PDP) format.
Users that receive product messages can add products to an shopping cart,
send the shopping cart to the business and share products with friends on WhatsApp.
Please note that to send these type of messages an WhatsApp business number needs to be linked to an Facebook business page.
Where products can be added via commerce manager. In the commerce manager a catalog of products can be made to send out via
product messages. For more details visit https://developers.facebook.com/docs/whatsapp/guides/commerce-guides
Example single product message
{
"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": "catalogid-from-commercemanager",
"product_retailer_id": "product-id-in-catalog"
}
}
}]
}
example list product message
{
"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"
}
]
}]
}
}
}]
}
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.
Location messages
To send a location to a user use the location object, which contains the following fields:
| Latitude | The latitude in degrees |
| Longitude | The longitude in degrees |
| SearchQuery | The address to display |
| Label | The label to display at the pin |
Example
{
"conversation": [
{
"location": {
"latitude": "51.603802",
"longitude": "4.770821",
"label": "CM HQ",
"searchQuery": "Konijnenberg 30"
}
}
]
}
Contacts
To send one or more contacts to a user use the Contacts array, which contains the fields described in WhatsApp for Business docs.
Note that the name.formatted_name and at least one of: name.first_name, name.last_name, name.middle_name, name.suffix, name.prefix is required.
Example
{
"conversation": [
{
"contacts": [
{
"addresses": [
{
"city": "Breda",
"country": "Netherlands",
"country_code": "NL",
"street": "Konijnenberg 30",
"type": "WORK",
"zip": "4825 BD"
}
],
"name": {
"formatted_name": "CM Developer",
"last_name": "Your last name"
}
}
]
}
]
}
Updated about 1 month ago