Managing templates

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

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

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 Build 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>. Examples are provided in the following sections.

Note that there are two versions of the Template Management API. Version 2 of the Template Management API was released on September 4, 2023. We recommend using this version of the Template Management API for all template management activities via API calls. In addition to the feature set included with Version 1, Version 2 also includes:

• Strongly typed translations field content, allowing the user to define the message using the same JSON structure used to define messages in a send message request

• Improved validation

• The option to override the omni-channel template configuration with a channel-specific template (for channels on which channel-specific templates can be created) using the channel_template_overrides field

Version 1

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:

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.

Version 2

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:

Sending omni-channel templates

For information on how to send an omni-channel template, see the sending omni-channel templates section of the sending messages page.

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 can be created using either the Sinch Build Dashboard or the Provisioning API. They are then uploaded to and approved by Facebook, and are required to send messages outside of the customer care session.

  Note:

  In addition creating WhatsApp templates, you can also edit active WhatsApp templates using the Sinch Build Dashboard or the Provisioning API's Update a template in project call. However, you can only update an active template a maximum of once a day and ten times a month.

• 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 examples, see the sending channel-specific templates section of the sending messages page.

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