Template messages
Sending a message outside of a 24-hour customer care session 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 business initiated 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 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 media and interactive templates.
The format of the keys in the parameter dictionary is of the following form:
<component_type>[<component_index>]<component_sub_type>[<parameter_index>]<parameter_field>
where:
-
<component_type>
must be set to one of
header
,body
orbutton
. - <component_index> is a 0-based index of the button in the template. There can be, at most, three 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
orurl
. - <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.*
Text Template
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"
}
}
}
}
}
}
Media Template
The WhatsApp channel allows you to send the following media types in the template header:
Document
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"
}
}
}
}
}
}
Video
The parameter fields for sending a video are 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"
}
}
}
}
}
}
Image
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"
}
}
}
}
}
}
Interactive Template
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.
These buttons can be attached to both text and media templates. However, you are only allowed to register templates that have, at most, one of these types of buttons. You can't have a registered template that has both call-to-action and quick reply buttons. Also, when using quick reply buttons in your templates you can have, at most, three buttons. When using call-to-action buttons you can have, at most, two 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:
When adding a quick_reply
button, the payload
field must be set even when empty. For example, you can set the quick_reply
button at index 0
to be empty by adding the following entry in the parameter dictionary:
"button[0]quick_reply[1]payload": ""
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"
}
}
}
}
}
}
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"
}
}
}
}
}
}