Sending a message outside of a 24-hour customer service window requires an approved template. Templates are generally constructed by Sinch based on your organization's needs. If you used the embedded signup process, you'll also have access to a set of default templates. Note the following:
Approved WhatsApp templates are not the same as omni-channel templates that you can use with the rest of the Conversation API. WhatsApp templates need to be approved by WhatsApp, and are not used on other Conversation API channels.
All marketing, utility, or authentication conversations on the WhatsApp channel must start with an “Opt-In” by the user. This can be collected through any third party channel. For example in an SMS message, a web form, or email. Businesses must also provide a method by which customers may opt-out of receiving future messages from your organization.
When using the WhatsApp channel, you may receive a
RECIPIENT_NOT_REACHABLEerror code if you send a marketing template message to a recipient, and the recipient is part of the current WhatsApp marketing message experiment.
When sending a template message, you need to specify the template name, language code, and the set of parameters defined in the template. Conversation API provides the capability to send channel-specific templates that use a key-value dictionary to specify the template parameters. Each key in the dictionary corresponds to a property of a template parameter as they're defined in WhatsApp public documentation for templates.
The format of the keys in the parameter dictionary is of the following form:
<component_type>[carousel_card_index]<card_component_type>[<component_index>]<component_sub_type>[<parameter_index>]<parameter_field>where:
- <component_type> must be set to one of
header,body,buttonorcarousel. - <carousel_card_index> is a 0-based index of the carousel card in the template. There can be, at most, ten cards included in the template. The <carousel_card_index> key is present and required only for the carousel component.
- <card_component_type> must be set to one of
header,bodyorbutton. The <card_component_type> key is present and required only for carousel component. - <component_index> is a 0-based index of the button in the template. There can be, at most, ten buttons. The <component_index> key is present and required only for button components.
- <component_sub_type> is present and required only for button components. It's set to either
quick_reply,url, orflow. - <parameter_index> is a 1-based index of the parameter for the given component.
- <parameter_field> is a property of the parameter. It can be one of
text,payload,document.,image., orvideo.*
When creating and populating templates, consider the following limitations:
- When creating a template, the template content field (i.e., the text body) can include up to 1024 characters.
- When sending a populated template that only includes a
bodycomponent with text, the total number of characters that may be included (after parameters have been populated) in thatbodycomponent is 32768. If any other components are included (for example, if aheaderis included), thebodycomponent may include up to 1024 characters after parameters have been populated. - When creating or sending a template that includes a
headerwith text, up to 60 characters may be included in theheaderfield (both before and after parameter population). - When calculating the number of characters included in a message in which the parameter placeholders have been populated, note that all regular characters and all formatting characters count against the total (regardless of how they are displayed in the message once it is received on a mobile device).
- Text Template
- Media Template
- Location Template
- Interactive Template
- Authentication Template
- Carousel Template
- Flow Template
- Order Details Template (Payments)
Below is an example of sending a text-only template with three body parameters and no header. The template name is text_template and the language code is en. This template message is sent using a Conversation API POST to the messages:send endpoint.
{
"message": {
"template_message": {
"channel_template": {
"WHATSAPP": {
"template_id": "text_template",
"language_code": "en",
"parameters": {
"body[1]text": "Value of first parameter",
"body[2]text": "Value of second parameter",
"body[3]text": "Value of third parameter"
}
}
}
}
}
}Below is an example of sending the same template with the fr language code. It also specifies a text header parameter:
{
"message": {
"template_message": {
"channel_template": {
"WHATSAPP": {
"template_id": "text_template",
"language_code": "fr",
"parameters": {
"header[1]text": "Value of header parameter",
"body[1]text": "Value of first parameter",
"body[2]text": "Value of second parameter",
"body[3]text": "Value of third parameter"
}
}
}
}
}
}Templates with text-only bodies can include up to 32768 characters.
The WhatsApp channel allows you to send the following media types in the template header:
The parameter fields for sending a document are:
| Parameter field key | Description | Required? |
|---|---|---|
| header[1]document.link | The URL of the document | Yes |
| header[1]document.provider.name | Provider to use when downloading the file | No |
| header[1]document.filename | The filename of the document | No |
Below is an example of sending a template with a document header and a single body parameter. The template name is document_template and the language code is en. This template message is sent using a Conversation API POST to the messages:send endpoint.
{
"message": {
"template_message": {
"channel_template": {
"WHATSAPP": {
"template_id": "document_template",
"language_code": "en",
"parameters": {
"header[1]document.link": "https://example.com/document.pdf",
"header[1]document.filename": "document.pdf",
"body[1]text": "Value of first parameter"
}
}
}
}
}
}The parameter fields for sending a video are:
| Parameter field key | Description | Required? |
|---|---|---|
| header[1]video.link | The URL of the video | Yes |
| header[1]video.provider.name | Provider to use when downloading the file | No |
Below is an example of sending a template with a video header and a single body parameter. The template name is video_template and the language code is en. This template message is sent using a Conversation API POST to the messages:send endpoint.
{
"message": {
"template_message": {
"channel_template": {
"WHATSAPP": {
"template_id": "video_template",
"language_code": "en",
"parameters": {
"header[1]video.link": "https://example.com/video.mp4",
"body[1]text": "Value of first parameter"
}
}
}
}
}
}The parameter fields for sending an image are:
| Parameter field key | Description | Required? |
|---|---|---|
| header[1]image.link | The URL of the image | Yes |
| header[1]image.provider.name | Provider to use when downloading the file | No |
Below is an example of sending a template with an image header and a single body parameter. The template name is image_template and the language code is en. This template message is sent using a Conversation API POST to the messages:send endpoint.
{
"message": {
"template_message": {
"channel_template": {
"WHATSAPP": {
"template_id": "image_template",
"language_code": "en",
"parameters": {
"header[1]image.link": "https://example.com/image.jpg",
"body[1]text": "Value of first parameter"
}
}
}
}
}
}If a business wishes to share location information with a user, the business can include that location information in the header of a message template. The parameter fields for sending a location in the header are:
| Parameter field key | Description | Required? |
|---|---|---|
| header[1]location.longitude | Longitude of the location | Yes |
| header[1]location.latitude | Latitude of the location | Yes |
| header[1]location.name | Name of the location | No |
| header[1]location.address | Address of the location | No |
Below is an example of sending a template with a location header and a single body parameter.
{
"message": {
"template_message": {
"channel_template": {
"WHATSAPP": {
"template_id": "location_template",
"language_code": "en",
"parameters": {
"header[1]location.latitude": "59.33273659725326",
"header[1]location.longitude": "18.018601842853027",
"header[1]location.name": "Sinch Office",
"header[1]location.address": "Lindhagensgatan 74, 112 18 Stockholm, Sweden",
"body[1]text": "Value of first parameter"
}
}
}
}
}
}Interactive templates allow you to send messages that include interactive buttons. WhatsApp offers two types of predefined buttons:
- Quick reply - Presents a button with predefined text which, when clicked, then returns a callback with a defined payload.
- Call-to-action - Presents a clickable action in WhatsApp to either call a phone number or to visit a website.
A business can manage and record marketing opt-outs using quick reply buttons.
These buttons can be attached to both text and media templates. However, you are only allowed to register templates that have, at most, ten buttons.
The parameter fields used to configure the buttons in the template are:
| Parameter field key | Description | Required? |
|---|---|---|
| button[n]url[1]text | Dynamic URL suffix for the URL button | Yes, if button at index n is a URL button |
| button[m]quick_reply[1]payload | Postback payload to be returned | Yes, if button at index m is a quick_reply button |
where n and m are indices of the buttons in the template.
Note the following:
When using
quick_replybuttons with other buttons,quick_replybuttons must be grouped together in the template. Use the index feature to designate the order in which the buttons appear and ensure thatquick_replybuttons are grouped together in the template.When adding a
quick_replybutton, thepayloadfield must be set, even when empty. For example, you can set thequick_replybutton at index0to be empty by adding the following entry in the parameter dictionary:"button[0]quick_reply[1]payload": ""
A business can manage and record marketing opt-outs using quick reply buttons.
Below is an example of sending a template with three quick reply buttons. The template also has one header and one body parameter. The template name is interactive_template_quick_reply and the language code is en. This template message is sent using a Conversation API POST to the messages:send endpoint.
{
"message": {
"template_message": {
"channel_template": {
"WHATSAPP": {
"template_id": "interactive_template_quick_reply",
"language_code": "en",
"parameters": {
"header[1]text": "Value of header parameter",
"body[1]text": "Value of first parameter",
"button[0]quick_reply[1]payload": "button0clicked",
"button[1]quick_reply[1]payload": "button1clicked",
"button[2]quick_reply[1]payload": "button2clicked"
}
}
}
}
}
}When a recipient presses a quick reply button, the sender/business receives an MO contact message. The contact message will contain the choice_response_message with a postback_data field. That field is populated with the payload of the quick reply button that was pressed (this content is specified when sending the original template message):
{
"app_id": "01FDEHES4Y3FRK0Q3RDV3T12VN",
"accepted_time": "2023-12-18T09:23:47.444Z",
"event_time": "2023-12-18T09:23:47.444Z",
"project_id": "c36f3d3d-1513-4edd-ae42-11995557ff61",
"message": {
"id": "01E6NKBV63YG6K01ENEW7S1N80",
"direction": "TO_APP",
"contact_message": {
"choice_response_message": {
"message_id": "01HHY3SZJ0RN5FWWM3XRSPMXS7",
"postback_data": "button0clicked"
},
"reply_to": {
"message_id": "01HHY3SZJ0RN5FWWM3XRSPMXS7"
}
},
"conversation_id": "01E6K4A8PGZ6MV0GD3C7M901MZ",
"contact_id": "01E6K4A8N3NANZ05VM0FS80EHD",
"metadata": "",
"accept_time": "2023-12-18T09:23:47.444Z"
}
}Below is an example of sending a template with two URL buttons (call-to-action). The template also has one header and one body parameter. The template name is interactive_template_call_to_action and the language code is en. This template message is sent using a Conversation API POST to the messages:send endpoint.
{
"message": {
"template_message": {
"channel_template": {
"WHATSAPP": {
"template_id": "interactive_template_call_to_action",
"language_code": "en",
"parameters": {
"header[1]text": "Value of header parameter",
"body[1]text": "Value of first parameter",
"button[0]url[1]text": "Value for URL suffix button 1",
"button[1]url[1]text": "Value for URL suffix button 2"
}
}
}
}
}
}If a business wants to send codes to verify a transaction or login attempt, an authentication template can be used. The parameter fields for sending a code via authentication template are:
| Parameter field key | Description | Required? |
|---|---|---|
| body[1]text | Code to verify a transaction or login | Yes |
| button[0]url[1]text | Code to verify a transaction or login | Yes |
Below is an example of the message payload when sending an authentication template:
{
"message": {
"template_message": {
"channel_template": {
"WHATSAPP": {
"template_id": "authentication_template",
"language_code": "en",
"parameters": {
"body[1]text": "123456",
"button[0]url[1]text": "123456"
}
}
}
}
}
}Depending on the definition of the template, this message will be displayed with a one-tap autofill button or a copy code button. Note that, when sending this type of message, the above structure must be followed exactly. Additionally, the values used to populate the body[1]text field and the button[0]url[1] field must match.
Below is an example of how an authentication template message might appear on a user's handset:
In the above image, the text reads <YOUR_verification_code> is your verification code. The message can also be configured to read <YOUR_verification_code> is your verification code. For your security, do not share this code. (if you opt to include a security warning during template configuration) or <YOUR_verification_code> is your verification code. This code expires in <YOUR_expiry_time_value> minutes. (if you opt to define an expiry time during template configuration).
Below is an example of sending a carousel template with two body parameters for the first card, one body parameter for the second card, and an image header parameter for each card. The template name is carousel_template and the language code is en. This template message is sent using a Conversation API POST to the messages:send endpoint.
{
"message": {
"template_message": {
"channel_template": {
"WHATSAPP": {
"template_id": "carousel_template",
"language_code": "en",
"parameters": {
"carousel[0]header[1]image.link": "https://example.com/image1.jpg",
"carousel[0]body[1]text": "Value of first parameter (first card)",
"carousel[0]body[2]text": "Value of second parameter (first card)",
"carousel[1]header[1]image.link": "https://example.com/image2.jpg",
"carousel[1]body[1]text": "Value of first parameter (second card)"
}
}
}
}
}
}The prerequisites for sending a Flow template message and the parameters used when sending a Flow template message are described below.
Before sending a template with a Flow button, you must have the following set up:
At least one Flow created and published in Meta's system.
For more details about creating Flows, see Sinch's Managing Flows documentation. You may also review the WhatsApp Flows section of Meta's documentation.
At least one message template with the specific Flow ID and Button with
FLOWtype created and approved by WhatsApp.For more details about creating Message Templates, the Create a template in project documentation in the WhatsApp Templates section of the Provisioning API API reference guide.
Supported parameter fields for a button with FLOW type in Message Templates are:
| Parameter field key | Description | Required? |
|---|---|---|
| button[n]flow[1]action.type | Required. The only supported value is action. | Yes |
| button[n]flow[1]action.token | Optional. Default value is "unused". | No |
| button[n]flow[1]action.data | Optional. A JSON object with the data payload for the first screen of the Flow. | No |
{
"message": {
"template_message": {
"channel_template": {
"WHATSAPP": {
"template_id": "flow_template",
"language_code": "en",
"parameters": {
"button[1]flow[1]action.type": "action"
}
}
}
}
}
}With an Order Details template, you can send WhatsApp Payments.
The prerequisites for sending an Order Details template message and the parameters used when sending an Order Details template message are described below.
Before sending a template with an Order Details button, you must have the following set up:
- A template with an
ORDER_DETAILSbutton component created and approved by WhatsApp.
A template message that includes an ORDER_DETAILS button type supports parameters starting with action. Each parameter in this table starts with button\[1]order\_details\[1]action..
| Parameter field key | Description | Required? |
|---|---|---|
| type | The only supported value is br for Brazil. | Yes |
| reference_id | The reference id for the order or invoice provided by the business. | Yes |
| type_of_goods | digital-goods or physical-goods | Yes |
| total_amount_value | The total amount to pay. Must be equal to order.subtotal_value + order.tax_value + order.shipping_value - order.discount_value. There is an offset of 100. For example, to represent an amount of 500, you must set the value to 50000. | Yes |
| order.subtotal_value | Subtotal value. There is an offset of 100. For example, to represent an amount of 500, you must set the value to 50000. | Yes |
| order.expiration_time | UTC time in seconds. The minimum threshold is 300 seconds. | Yes |
| order.expiration_description | Text explanation for when the order will expire. Max 120 characters. | Yes |
| order.tax_value | Tax value. There is an offset of 100. For example, to represent an amount of 500, you must set the value to 50000. | Yes |
| order.tax_description | Max 60 characters. | No |
| order.catalog_id | ID of the Facebook catalog being used by the business. | No |
| order.shipping_value | Shipping value. There is an offset of 100. For example, to represent an amount of 500, you must set the value to 50000. | No |
| order.shipping_description | Max 60 characters. | No |
| order.discount_value | Discount value. There is an offset of 100. For example, to represent an amount of 500, you must set the value to 50000. | No |
| order.discount_description | Max 60 characters. | No |
| order.discount_program_name | Text used for defining incentivised orders. If order is incentivised, the merchant needs to define this information. Max 60 characters. | No |
| order.items[i]retailer_id | The content ID for item i in the order from your catalog. | Yes |
| order.items[i]name | The item's name to be displayed to the user. Max 60 characters. | Yes |
| order.items[i]amount | The item price. There is an offset of 100. For example, to represent an amount of 500, you must set the value to 50000. | Yes |
| order.items[i]quantity | The quantity of this item in the order. | Yes |
| order.items[i]sale_amount_value | The discounted price per item. There is an offset of 100. For example, to represent an amount of 500, you must set the value to 50000. | No |
| order.payment_settings[i]type | Either pix, payment_link, or boleto. | Yes |
| order.payment_settings[i]pix_code | The dynamic Pix code which will be copied by the buyer. | Yes, if payment_settings.type is pix |
| order.payment_settings[i]pix_merchant_name | The name of the account holder. | Yes, if payment_settings.type is pix |
| order.payment_settings[i]pix_key | Pix key. | Yes, if payment_settings.type is pix |
| order.payment_settings[i]pix_key_type | One of CPF, CJPJ, EMAIL, PHONE, or EVP. | Yes, if payment_settings.type is pix |
| order.payment_settings[i]payment_link_uri | The Payment Link's URI which will be opened in the web browser when the user taps the Payment Link button. | Yes, if payment_settings.type is payment_link |
| order.payment_settings[i]boleto_digitable_line | The Boleto digitable line (code) which will be copied to the clipboard when the user taps the Boleto button. | Yes, if payment_settings.type is boleto |
- An order must contain at least one item. The first item in the order has index 1.
- An order must include the
payment_settingsset of parameters and can include, at most, two sets.
The following sub-sections provide examples of payloads for Order Details template messages:
The following code sample provides an example of a payload for an Order Details template message customized for Pix:
{
"message": {
"template_message": {
"channel_template": {
"WHATSAPP": {
"template_id": "order_details_template",
"language_code": "en",
"parameters": {
"body[1]text": "John",
"header[1]image.link": "https://www.example.com/images/image.jpg",
"button[1]order_details[1]action.type": "br",
"button[1]order_details[1]action.reference_id": "1234",
"button[1]order_details[1]action.type_of_goods": "digital-goods",
"button[1]order_details[1]action.total_amount_value": "601",
"button[1]order_details[1]action.order.items[1]retailer_id": "retailer1",
"button[1]order_details[1]action.order.items[1]name": "Item name 1",
"button[1]order_details[1]action.order.items[1]amount_value": "200",
"button[1]order_details[1]action.order.items[1]quantity": "1",
"button[1]order_details[1]action.order.items[2]retailer_id": "retailer2",
"button[1]order_details[1]action.order.items[2]name": "Item name 2",
"button[1]order_details[1]action.order.items[2]amount_value": "120",
"button[1]order_details[1]action.order.items[2]sale_amount_value": "100",
"button[1]order_details[1]action.order.items[2]quantity": "3",
"button[1]order_details[1]action.order.subtotal_value": "500",
"button[1]order_details[1]action.order.tax_value": "100",
"button[1]order_details[1]action.order.expiration_time": "1757392706",
"button[1]order_details[1]action.order.expiration_description": "Expiration description",
"button[1]order_details[1]action.order.payment_settings[1]type": "pix",
"button[1]order_details[1]action.order.payment_settings[1]pix_code": "1234",
"button[1]order_details[1]action.order.payment_settings[1]pix_merchant_name": "Test merchant",
"button[1]order_details[1]action.order.payment_settings[1]pix_key": "asdf@example.com",
"button[1]order_details[1]action.order.payment_settings[1]pix_key_type": "EMAIL"
}
}
}
}
}
}The following code sample provides an example of a payload for an Order Details template message customized for a payment link:
{
"message": {
"template_message": {
"channel_template": {
"WHATSAPP": {
"template_id": "order_details_template",
"language_code": "en",
"parameters": {
"body[1]text": "John",
"header[1]image.link": "https://www.example.com/images/image.jpg",
"button[1]order_details[1]action.type": "br",
"button[1]order_details[1]action.reference_id": "1234",
"button[1]order_details[1]action.type_of_goods": "digital-goods",
"button[1]order_details[1]action.total_amount_value": "601",
"button[1]order_details[1]action.order.items[1]retailer_id": "retailer1",
"button[1]order_details[1]action.order.items[1]name": "Item name 1",
"button[1]order_details[1]action.order.items[1]amount_value": "200",
"button[1]order_details[1]action.order.items[1]quantity": "1",
"button[1]order_details[1]action.order.items[2]retailer_id": "retailer2",
"button[1]order_details[1]action.order.items[2]name": "Item name 2",
"button[1]order_details[1]action.order.items[2]amount_value": "120",
"button[1]order_details[1]action.order.items[2]sale_amount_value": "100",
"button[1]order_details[1]action.order.items[2]quantity": "3",
"button[1]order_details[1]action.order.subtotal_value": "500",
"button[1]order_details[1]action.order.tax_value": "100",
"button[1]order_details[1]action.order.expiration_time": "1757392706",
"button[1]order_details[1]action.order.expiration_description": "Expiration description",
"button[1]order_details[1]action.order.payment_settings[1]type": "payment_link",
"button[1]order_details[1]action.order.payment_settings[1]payment_link_uri": "https://example.com/pay"
}
}
}
}
}
}The following code sample provides an example of a payload for an Order Details template message customized for Boleto:
{
"message": {
"template_message": {
"channel_template": {
"WHATSAPP": {
"template_id": "order_details_template",
"language_code": "en",
"parameters": {
"body[1]text": "John",
"header[1]image.link": "https://www.example.com/images/image.jpg",
"button[1]order_details[1]action.type": "br",
"button[1]order_details[1]action.reference_id": "1234",
"button[1]order_details[1]action.type_of_goods": "digital-goods",
"button[1]order_details[1]action.total_amount_value": "601",
"button[1]order_details[1]action.order.items[1]retailer_id": "retailer1",
"button[1]order_details[1]action.order.items[1]name": "Item name 1",
"button[1]order_details[1]action.order.items[1]amount_value": "200",
"button[1]order_details[1]action.order.items[1]quantity": "1",
"button[1]order_details[1]action.order.items[2]retailer_id": "retailer2",
"button[1]order_details[1]action.order.items[2]name": "Item name 2",
"button[1]order_details[1]action.order.items[2]amount_value": "120",
"button[1]order_details[1]action.order.items[2]sale_amount_value": "100",
"button[1]order_details[1]action.order.items[2]quantity": "3",
"button[1]order_details[1]action.order.subtotal_value": "500",
"button[1]order_details[1]action.order.tax_value": "100",
"button[1]order_details[1]action.order.expiration_time": "1757392706",
"button[1]order_details[1]action.order.expiration_description": "Expiration description",
"button[1]order_details[1]action.order.payment_settings[1]type": "boleto",
"button[1]order_details[1]action.order.payment_settings[1]boleto_digitable_line": "28270987896223635548259530554735491829813298983"
}
}
}
}
}
}The following code sample provides an example of a payload for an Order Details template message customized for a payment link and Pix:
{
"message": {
"template_message": {
"channel_template": {
"WHATSAPP": {
"template_id": "order_details_template",
"language_code": "en",
"parameters": {
"body[1]text": "John",
"header[1]image.link": "https://www.example.com/images/image.jpg",
"button[1]order_details[1]action.type": "br",
"button[1]order_details[1]action.reference_id": "1234",
"button[1]order_details[1]action.type_of_goods": "digital-goods",
"button[1]order_details[1]action.total_amount_value": "601",
"button[1]order_details[1]action.order.items[1]retailer_id": "retailer1",
"button[1]order_details[1]action.order.items[1]name": "Item name 1",
"button[1]order_details[1]action.order.items[1]amount_value": "200",
"button[1]order_details[1]action.order.items[1]quantity": "1",
"button[1]order_details[1]action.order.items[2]retailer_id": "retailer2",
"button[1]order_details[1]action.order.items[2]name": "Item name 2",
"button[1]order_details[1]action.order.items[2]amount_value": "120",
"button[1]order_details[1]action.order.items[2]sale_amount_value": "100",
"button[1]order_details[1]action.order.items[2]quantity": "3",
"button[1]order_details[1]action.order.subtotal_value": "500",
"button[1]order_details[1]action.order.tax_value": "100",
"button[1]order_details[1]action.order.expiration_time": "1757392706",
"button[1]order_details[1]action.order.expiration_description": "Expiration description",
"button[1]order_details[1]action.order.payment_settings[1]type": "pix",
"button[1]order_details[1]action.order.payment_settings[1]pix_code": "1234",
"button[1]order_details[1]action.order.payment_settings[1]pix_merchant_name": "Test merchant",
"button[1]order_details[1]action.order.payment_settings[1]pix_key": "asdf@example.com",
"button[1]order_details[1]action.order.payment_settings[1]pix_key_type": "EMAIL",
"button[1]order_details[1]action.order.payment_settings[2]type": "payment_link",
"button[1]order_details[1]action.order.payment_settings[2]payment_link_uri": "https://example.com/pay",
}
}
}
}
}
}An Order Details template message can include, at most, two types of payment settings.