# WhatsApp Interactive Message Templates

{% hint style="warning" %}
Always use the ![](https://3868048845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRJrT3ZeHQnYGnLALMybb%2Fuploads%2Fgit-blob-5e19c5997155d481f1b77468c881d6928be37d95%2FAPI_copy_example.png?alt=media) **Copy** icon in the example field when copying examples. Manual copy and paste is known to cause data format errors.
{% endhint %}

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.

<figure><img src="https://3868048845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRJrT3ZeHQnYGnLALMybb%2Fuploads%2Fgit-blob-29bc637b2fcb0fec27f09686a6bcfb7917a985ad%2FJSON_data.png?alt=media" alt=""><figcaption></figcaption></figure>

### Prerequisites <a href="#format-of-the-json-call-to-the-agent" id="format-of-the-json-call-to-the-agent"></a>

Interactive templates need to be created, then they must be approved by Facebook.

### JSON data format used as an input of the Agent API call for interactive templates <a href="#format-of-the-json-call-to-the-agent" id="format-of-the-json-call-to-the-agent"></a>

A WhatsApp template payload comprises 6 elements:

* A **template\_name** corresponding to the template name defined in WhatsApp Manager

{% hint style="info" %}
The message template name field is limited to 512 characters, see the *Limitations* section of the [WhatsApp templates guide](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/).
{% endhint %}

* A **language (optional)** *<mark style="color:green;">(since release 22.11)</mark>* corresponding to the language to be used to send the template

{% hint style="info" %}
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.
{% endhint %}

* A **header \_\*\*\*\***\_\*\* (optional)\*\* found at the top of the template
* A **body** that comes after the header and contains the content of the template

{% hint style="info" %}
The message template content field is limited to 1024 characters, see the *Limitations* section of the [WhatsApp templates guide](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/).
{% endhint %}

* 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.

<figure><img src="https://3868048845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRJrT3ZeHQnYGnLALMybb%2Fuploads%2Fgit-blob-90faf234b1a83f1938e8f8929e864f2d6e1888d0%2F4%20parts.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
These components can be customized using parameters.
{% endhint %}

#### Format to send to the Agent to display the template

{% code overflow="wrap" %}

```json
{
   "type": "send_template", // call to the send_template action
   "payload": {
      "template_name": "welcome_terms_conditions_v3",// name of the template to call
      "language":"CHINESE_CHN", // language to be used to send the template; this language will override the user preferred language
      "header": {}, // variable to send to the header (only one is accepted)
      "body": [], // variables to send to the body
      "buttons": [] // buttons to display
   }
}
```

{% endcode %}

{% hint style="info" %}
The template name is case-sensitive.
{% endhint %}

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.

### Header format

The header property value is a JSON object which contains either the text value of a variable, or a link to a file.

#### Example 1: Text

<figure><img src="https://3868048845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRJrT3ZeHQnYGnLALMybb%2Fuploads%2Fgit-blob-0e8e521f051c862f4f5de0ecf146ac39c95b5812%2FExample%201%20Text.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
WhatsApp Manager only supports 1 variable in the header text.
{% endhint %}

```json
"header": {
   "type": "TEXT",
   "text": "<value>" // replaces {{1}} in the screenshot above
}
```

#### Example 2: Redirection parameter

<figure><img src="https://3868048845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRJrT3ZeHQnYGnLALMybb%2Fuploads%2Fgit-blob-49dd4257d9b167869acb5b542e0003477bc93288%2FExample%202%20Redirection%20parameter.png?alt=media" alt=""><figcaption></figcaption></figure>

```json
"header": {
   "type": "REDIRECT",
   "streamId": "<streamId where the link should be redirected>"   
}
```

{% hint style="info" %}
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.
{% endhint %}

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:`` `` `<mark style="color:blue;">`https://wa.me/1XXXXXXXXXX`</mark>

#### Example 3: Send a template with a PDF file in the header

<figure><img src="https://3868048845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRJrT3ZeHQnYGnLALMybb%2Fuploads%2Fgit-blob-ff37733c793ca51ad0ab1326f9549e9cc3593353%2FExample%203%20Template%20with%20PDF%20in%20header.png?alt=media" alt=""><figcaption></figcaption></figure>

```json
"header": {
  "type": "DOCUMENT":
  "link": "<public link to the document>"
}
```

#### Example 4: Send a template with a PDF file in the header (and a file sent in the request body)

```json
"header": {
    "type": "DOCUMENT"
}
```

The document parameters can be one of the following three types: `IMAGE`, `VIDEO` or `DOCUMENT`.

{% hint style="info" %} <mark style="color:green;">**From release 22.11**</mark>, all the types are supported. Before, only the DOCUMENT type was supported.
{% endhint %}

{% hint style="info" %}
The link associated to the document must be publicly accessible.
{% endhint %}

* 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.

```json
{
  "type": "send_template",
  "payload": {
    "template_name": "template-name-3",
    "header": {
      "type": "DOCUMENT"
    }
  }
}
```

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.

{% hint style="info" %}
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.
{% endhint %}

### Body format

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.

#### Example of a body object

```json
"body": [
  {
    // {{1}}
    "type": "TEXT",
    "text": "<value as string variable1>"
  },
  {
    // {{2}}
    "type": "TEXT",
    "text": "<value as string variable2>"
  },
  {
    // you can have a look at the example described on header section
    "type": "REDIRECT",
    "streamId": "<streamId where the link should be redirected>",
    "prefilled_text" : "<prefilled message>" // added since 22.11 optional
    // After clicking on the redirection link, 
    // the prefilled message is ready to be sent by the WhatsApp user. 
    // (the user doesn’t need to type it)
  },
]
```

For example, you can have the template below:

<figure><img src="https://3868048845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRJrT3ZeHQnYGnLALMybb%2Fuploads%2Fgit-blob-e65d91998508f7654a755a1e31d24825b88d299b%2Fsample_template.png?alt=media" alt=""><figcaption></figcaption></figure>

With the following JSON data:

```json
"body": [
  {
    // {{1}}
    "type": "TEXT",
    "text": "John"
  },
  {
    // {{2}}
    "type": "TEXT",
    "text": "Interactive templates"
  },
  {
    // {{2}}
    "type": "TEXT",
    "text": "June 22, 2022"
  }
]
```

### Footer format

Nothing needs to be provided in the JSON data, as the footer is static.

### Button format

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.

#### Dynamic URL

<figure><img src="https://3868048845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRJrT3ZeHQnYGnLALMybb%2Fuploads%2Fgit-blob-41a21fb8c1b14e58049e332d0aea18eb415c93f2%2FDynamic%20URL.png?alt=media" alt=""><figcaption></figcaption></figure>

#### Static URL

{% hint style="info" %}
**Static URL** buttons and **QUICK\_REPLY** buttons do not require any parameter.
{% endhint %}

```json
"buttons": [
  {
    "type": "URL",
    "index": 0, // corresponds to the index of the buttons listed in the WhatsApp template
    "path": "<path of the URL>"
  }
]
```

{% hint style="warning" %}
**wa.me** URLs cannot be used in buttons.
{% endhint %}

#### **Example 1: Dynamic URL in first place**

<figure><img src="https://3868048845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRJrT3ZeHQnYGnLALMybb%2Fuploads%2Fgit-blob-3bb8650dbd51606160902e135812975052eeda26%2FDynamic%20URL%20in%20first%20place.png?alt=media" alt=""><figcaption></figcaption></figure>

Data needs to be provided for the first dynamic URL button ("index": 0):

```json
"buttons": [
  {
    "type": "URL",
    "index": 0, // corresponds to the index of the buttons listed in the WhatsApp template
    "path": "<path of the URL>" // replace {{1}} in the first button with the dynamic URL
  }
]
```

**Example 2: Dynamic URL in second place**

Data needs to be provided for the second dynamic URL button ("index": 1)

<figure><img src="https://3868048845-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FRJrT3ZeHQnYGnLALMybb%2Fuploads%2Fgit-blob-97bec82ce16ee3d58611b0e53e8f42610cdcc385%2FDynamic%20URL%20in%20second%20place.png?alt=media" alt=""><figcaption></figcaption></figure>

```json
"buttons": [
  {
    "type": "URL",
    "index": 1, // corresponds to the index of the second button
    "path": "<path of the URL>" // replace {{1}} in the second button with the dynamic URL
  }
]
```

{% hint style="info" %}
If the WhatsApp [guidelines for message templates](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines/) are not followed, messages will not be sent.
{% endhint %}