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 and KakaoTalk templates are the only supported channel-specific templates, and they're stored by Facebook WhatsApp Business API or KakaoTalk.

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

Creating, updating, listing and deleting omni-channel templates is done through the Template Management API which is currently available in the following regions:

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:

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

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 API have the following properties:

Each translation object has the following properties:

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

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.

Channel-specific Templates

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

Currently, WhatsApp and KakaoTalk 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.

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:

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.

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

• WhatsApp Channel Support
• KakaoTalk Channel Support

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:

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.