24.03 PROD

WhatsApp Interactive Message Templates

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.

Prerequisites

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

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.

Format to send to the Agent to display the template

{
   "type": "send_template", // call to the send_template action
   "payload": {
      "template_name": "welcome_terms_conditions_v3",// name of the template to call
      "header": {}, // variable to send to the header (only one is accepted)
      "body": [], // variables to send to the body
      "buttons": [] // buttons to display
   }
}

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.

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

WhatsApp Manager only supports 1 variable in the header text.

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

Example 2: Redirection parameter

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

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

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

"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)

"header": {
    "type": "DOCUMENT"
}

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.

{
  "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.

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.

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

"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:

With the following JSON data:

"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

Static URL

Static URL buttons and QUICK_REPLY buttons do not require any parameter.

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

wa.me URLs cannot be used in buttons.

Example 1: Dynamic URL in first place

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

"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)

"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
  }
]

If the WhatsApp guidelines for message templates are not followed, messages will not be sent.

PreviousTenant API

Last updated