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:

RegionHost
UShttps://us.template.api.sinch.com
EUhttps://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:

FieldTypeDescription
descriptionstringTemplate description.
default_translationstringA translation to use if none given when sending a template message. Must be a valid BCP-47 language code.
channelstringThe Template Management API can store messages in different formats. The omni-channel templates use CONVERSATION as channel.
translationsarray of objectsList of translations for the template.

Each translation object has the following properties:

FieldTypeDescription
language_codestringThe BCP-47 language code, such as en-US or sr-Latn.
versionstringThe version of this template translation.
variablesarray of objectsList of expected variables in the template translation. It's used to validate send template requests.
contentstringThe 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:

FieldTypeDescription
keystringThe key with which the variable is referred to in the template content placeholders example, <key>
preview_valuestringA 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 message (object) or Card Message (object) or Carousel Message (object) or Choice Message (object) or Location message (object) or Media message (object) or Template Message (object) or List Message (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.

We'd love to hear from you!
Rate this content:
Still have a question?
 
Ask the community.