WhatsApp Interactive Message Templates
Last updated
Last updated
Always use the Copy icon in the example field when copying examples. Manual copy and paste is known to cause data format errors.
With the support of your TAM, you can configure structured objects to use WhatsApp interactive message templates, which allow you to deliver more information without being restricted by the 24-hour window.
The current list includes:
Messages containing quick reply buttons, where clicking the button sends into the room a reply that the bot is able to read in order to take further action if required.
Links only used on our side: we download the attachment and upload it on WhatsApp, the WhatsApp user does not see any difference if we use a link or an attachment.
Messages including in the body hyperlinks that redirect the user to an existing WhatsApp Connect chat room (given the customer provides the room information into the JSON structured object).
The Agent API (see https://developers.symphony.com/restapi/reference/create-message-v4) is used to send a message in an existing stream which accepts messageML and JSON data formats.
JSON data sent in a message can be interpreted in the aim to tell the Agent to display an interactive template on WhatsApp through the WhatsApp gateway.
Interactive templates need to be created, then they must be approved by Facebook.
A WhatsApp template payload comprises 6 elements:
A template_name corresponding to the template name defined in WhatsApp Manager
The message template name field is limited to 512 characters, see the Limitations section of the WhatsApp templates guide.
A language (optional) (since release 22.11) corresponding to the language to be used to send the template
The language can be CHINESE_CHN, CHINESE_HKG, CHINESE_TAI, JAPANESE, etc. as described in the WhatsApp contact preferred language API documentation section.
This language will override the user preferred language. If the template does not exist in this language, English language will used instead.
A header _****_** (optional)** found at the top of the template
A body that comes after the header and contains the content of the template
The message template content field is limited to 1024 characters, see the Limitations section of the WhatsApp templates guide.
A footer (optional) that is at the bottom of the template
Any button (optional)
These 4 parts correspond to the user interface that is used to define a template in WhatsApp Manager.
These components can be customized using parameters.
The template name is case-sensitive.
We can use the data object above to ask customers to provide all the information we need to send the template:
Template name
Parameters in the header (optional)
Parameters in the body (optional)
Buttons (optional)
Unlike the body and the header, the footer does not contain any parameters, only static data.
The type field allows to define the action targeted by the JSON message. In the ‘send_template’ case, the WhatsApp gateway interprets all the information from the payload object, and then sends the related template on WhatsApp.
The header property value is a JSON object which contains either the text value of a variable, or a link to a file.
WhatsApp Manager only supports 1 variable in the header text.
Please note that the redirect variable ( {{1}} ) in the template needs a space before and after for the redirection link to work in the message.
In the example above, if the streamId matches the right room, the template will be displayed as below (the wa.me URL is built from the streamId):
Click on the link to contact your advisor:`` ``
https://wa.me/1XXXXXXXXXX
The document parameters can be one of the following three types: IMAGE
, VIDEO
or DOCUMENT
.
From release 22.11, all the types are supported. Before, only the DOCUMENT type was supported.
The link associated to the document must be publicly accessible.
If the link of the document is present, the template will retrieve it, and then use a related PDF file found as an attachment field of the template message.
If both a link and an attachment are present (the link of the document in the payload, and the attachment in the request body), the link will be used.
If no link is present and there are multiple attachments in the request body, the first attachment in the template will be used.
In the example above, the backend checks if the parameters
object contains the type DOCUMENT
, and if the attachment
field is pointing to a file link.
If the corresponding file is correctly retrieved, it will extract the data and the fileName in order to upload it directly on WhatsApp.
When performing a file upload operation using a business API, the content type must be set to application/pdf in order for the message to be sent.
The body field is an array that can be either empty or contain a sub-object as JSON object.
Each sub-object represents the text value of a variable declared in the related template.
The order of the sub-objects follows the order of the variables declaration in the template.
The sub-object must have a type attribute which supports two possible values: TEXT or REDIRECT:
If the sub-object is TEXT, an additional attribute named text
must be filled.
If the sub-object is REDIRECT, the additional field named text
is optional, unlike the field streamId
which is mandatory.
For example, you can have the template below:
With the following JSON data:
Nothing needs to be provided in the JSON data, as the footer is static.
The JSON data should only contain data for buttons using the dynamic URL type. For static URLs, the information is already present in the WhatsApp templates.
Static URL buttons and QUICK_REPLY buttons do not require any parameter.
wa.me URLs cannot be used in buttons.
Data needs to be provided for the first dynamic URL button ("index": 0):
Example 2: Dynamic URL in second place
Data needs to be provided for the second dynamic URL button ("index": 1)
If the WhatsApp guidelines for message templates are not followed, messages will not be sent.