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 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_REACHABLE error 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 media and interactive templates.

The format of the keys in the parameter dictionary is of the following form:

Copy
Copied
<component_type>[<component_index>]<component_sub_type>[<parameter_index>]<parameter_field>

where:

  • <component_type> must be set to one of header , body or button .
  • <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 or url .
  • <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. , or video.*

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.

Copy
Copied
{
  "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:

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

Copy
Copied
{
  "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:

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.

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

Copy
Copied
{
  "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"
          }
        }
      }
    }
  }
}

Location Template

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.

Copy
Copied
{
  "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 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.
Opt-outs:

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:

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:

Copy
Copied
"button[0]quick_reply[1]payload": ""

Quick reply example

Opt-outs:

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.

Copy
Copied
{
  "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"
          }
        }
      }
    }
  }
}

Quick reply response example

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

Copy
Copied
{
  "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"
  }
}

Call-to-action example

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.

Copy
Copied
{
  "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"
          }
        }
      }
    }
  }
}

Authentication Template

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 sending an authentication template:

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

We'd love to hear from you!
Rate this content:
Still have a question?
 
Ask the community.
SecurityPrivacyLegal & ComplianceCookie Statement
© 2024 Sinch. All rights reserved.