Working with templates

Managing and send templates messages with the Sinch Conversation API.

Introduction

Conversation API supports sending template messages where all or parts of the message content is pre-defined. The message template can also contain dynamic content which is populated when sending the message using template parameters.

There are two types of templates which can be used when sending a template message:

Omni-channel
Channel-specific

The format of the omni-channel templates is exactly the same as the format of the message field of the messages:send request body. The omni-channel templates are stored and managed by Template Management API.

The channel-specific templates are stored and managed by the channels, and are only referenced when sending through Conversation API. Currently, WhatsApp, KakaoTalk, and WeChat templates are the only supported channel-specific templates, and they're stored by Facebook WhatsApp Business API, KakaoTalk, or WeChat.

Conversation API Omni-channel Templates

The omni-channel templates use Conversation API generic message format and therefore, can define a generic rich message or a concrete channel message by using the channel override feature of Conversation API.

It's easy to see how an omni-channel template will render on a specific channel by using the transcoding (messages:transcode) endpoint of the Conversation API.

The omni-channel templates are versioned and support storing message content for different languages.

Managing omni-channel templates using the Message Composer

You can create, update, and delete omni-channel templates using the Message Composer tool of the Sinch Customer Dashboard.If you are unfamiliar with the Message Composer tool, we encourage you to view the articles with the Message Composer tag on the Sinch Community site. They provide more information about the tool, including how to create an omni-channel template using the Message Composer.

Managing omni-channel templates using API calls

You can create, update, list, and delete omni-channel templates through the Template Management API, which is currently available in the following regions:

Region	Host
US	`https://us.template.api.sinch.com`
EU	`https://eu.template.api.sinch.com`

Templates are only stored in the region they're created and can only be used by Conversation API apps created in the same region. Accessing the Template Management API requires a valid access token for your Sinch project ID. To get an access token, you first need to create an Access Key in Sinch Customer Dashboard and store the Key Secret in a secure location.

Once you have a Key ID and Key Secret, obtaining a valid OAuth2 Access Token for the Template Management API is done as follows:

Copy

Copied

curl https://auth.sinch.com/oauth2/token -d grant_type=client_credentials --user <key_id>:<key_secret>

With the obtained Access Token you can, for example, store a text message template with a single English translation for a project with ID <Project ID>:

Version 1

Copy

Copied

curl -X POST \
'https://us.template.api.sinch.com/v1/projects/<Project ID>/templates' \
-H 'Content-Type: application/json' --header 'Authorization: Bearer <Access token>' \
-d '{
  "description": "English text template with one parameter using Conversation API generic format.",
  "default_translation": "en",
  "channel": "CONVERSATION",
  "translations": [{
    "language_code": "en",
    "version": "20201130",
    "variables": [{
      "key": "name",
      "preview_value": "Mr Jones"
    }],
    "content": "{ \"text_message\": { \"text\": \"Hi ${name}.\" }}"
  }]
}'

The templates stored in the Template Management V1 API have the following properties:

Field	Type	Description
description	string	Template description.
default_translation	string	A translation to use if none given when sending a template message. Must be a valid BCP-47 language code.
channel	string	The Template Management API can store messages in different formats. The omni-channel templates use `CONVERSATION` as channel.
translations	array of objects	List of translations for the template.

Each translation object has the following properties:

Field	Type	Description
language_code	string	The BCP-47 language code, such as `en-US` or `sr-Latn`.
version	string	The version of this template translation.
variables	array of objects	List of expected variables in the template translation. It's used to validate send template requests.
content	string	The template definition. Omni-channel templates are escaped JSON representation of Conversation API generic message format.

Each variable object in the variables array has the following properties:

Field	Type	Description
key	string	The key with which the variable is referred to in the template content placeholders example, `<key>`
preview_value	string	A string representation to be used in the template previewers.

The Template Management API can be used to store both omni-channel templates potentially containing channel overrides or pure channel templates. For using the template when sending a template message with Conversation API, you need to use omni-channel templates. Set the channel to CONVERSATION and use escaped JSON representation of Conversation API generic message format as content.

Version 2

Copy

Copied

curl -X POST \
'https://us.template.api.sinch.com/v2/projects/<Project ID>/templates' \
-H 'Content-Type: application/json' --header 'Authorization: Bearer <Access token>' \
-d '{
  "description": "English text template with one parameter using Conversation API generic format.",
  "default_translation": "en-US",
  "translations": [{
    "language_code": "en-US",
    "version": "1",
    "variables": [{
      "key": "name",
      "preview_value": "Mr Jones"
    }],
    "channel_template_overrides": {
        "WHATSAPP": {
            "template_reference": {
                "template_id": "21123123",
                "version": "1",
                "language_code": "en-US",
                "parameters": {
                    "body[1]text": "Default value"
                }
            },
            "parameter_mappings": {
                "body[1]text": "name"
            }
        }
    },
    "text_message": {
        "text": "text message"
    }
  }]
}'

The templates stored in the Template Management V2 API have the following properties:

description	string The description of the template.
version	integer The version of the template. While creating a template, this will be defaulted to 1. When updating a template, you must supply the latest version of the template in order for the update to be successful.
default_translation	string The default translation to use if not specified. Specified as a BCP-47 `language_code` and the `language_code` must exist in the translations list.
	Array of Text (object) or Card (object) or Carousel (object) or Choice (object) or Location (object) or Media (object) or Template Message (object) or List (object) (v2TemplateTranslation)
create_time	string <date-time> Timestamp when the template was created.
update_time	string <date-time> Timestamp when the template was updated.

Channel-specific Templates

With the Conversation API, you can reference channel-defined templates when sending a template message.

Currently, WhatsApp, KakaoTalk, and WeChat are the only channels that have channel-specific templates. WhatsApp templates are uploaded to and approved by Facebook, and are required to send messages outside of the customer care session. KakaoTalk templates (Alimtalk) are registered by Sinch on behalf of the customer and need to be approved by KakaoTalk. These templates are required to send messages, such as notifications or delivery status messages. WeChat templates are pre-defined by WeChat. You must go to the Template Library section in your WeChat Admin portal, choose the templates that fit your use cases, and add those templates to your account.

Once a template has been created and approved, you can start using it with Conversation API to send template messages to the channel. For example:

Copy

Copied

curl -X POST \
'https://us.conversation.api.sinch.com/v1/projects/<Project ID>/messages:send' \
-H 'Content-Type: application/json' --header 'Authorization: Bearer <Access token>' \
-d '{
    "app_id": "<App Id>",
    "recipient": {
      "contact_id": "<Contact Id>"
    },
    "message": {
        "template_message": {
            "channel_template": {
                "WHATSAPP": {
                    "template_id": "<Whatsapp Template Id>",
                    "language_code": "en",
                    "parameters": {
                        "header[1]image.link": "https://example.com",
                        "body[1]text": "Value of first parameter"
                    }
                }
            }
        }
    },
    "channel_priority_order": [
        "WHATSAPP"
    ]
}'

The snip above sends a template message to a recipient with <Contact Id> and tries only the WHATSAPP channel. The message being sent is a template message referencing a WhatsApp channel-defined template with ID <Whatsapp Template Id> and language code en. It also specifies the parameters defined in the template as part of parameters field.

Note

When sending an AlimTalk template message on the KakaoTalk channel, the language_code value is not used. When you register a KakaoTalk AlimTalk message template, each language has its own unique template ID. Therefore, it is not possible to register multiple language codes to the same template_id for KakaoTalk templates.

You can read more about sending channel-specific templates on the following pages:

Omni- and channel-specific templates can both be used when sending a message. This is useful in several scenarios. For example, you can enable channel fallback in case the recipient has no capability on the WhatsApp channel:

Copy

Copied

curl -X POST \
'https://us.conversation.api.sinch.com/v1/projects/<Project ID>/messages:send' \
-H 'Content-Type: application/json' --header 'Authorization: Bearer <Access token>' \
-d '{
    "app_id": "<App Id>",
    "recipient": {
      "contact_id": "<Contact Id>"
    },
    "message": {
        "template_message": {
            "channel_template": {
                "WHATSAPP": {
                    "template_id": "<Whatsapp Template Id>",
                    "language_code": "en",
                    "parameters": {
                        "header[1]image.link": "https://example.com",
                        "body[1]text": "Value of first parameter"
                    }
                }
            },
            "omni_template": {
                "template_id": "<Omni Template Id>",
                "version": "<Omni Version Id>",
                "language_code": "en",
                "parameters": {
                    "name": "Ms Smith"
                }
            }
        }
    },
    "channel_priority_order": [
        "WHATSAPP", "SMS"
    ]
}'

The Conversation API will use the channel-specific template if one exists for the channel. Otherwise, it will fallback to the omni template.