Skip to content
Conversation API/
/Templates V1

Template Management API (457aacb5)

Overview

The Template Management API offers a way to manage templates that can be used together with the Conversation API. Note that you may also use the Message Composer tool on the Sinch Customer Dashboard to manage templates.

One can view a template as a pre-defined message that can optionally contain some parameters to facilitate some customization of the pre-defined message. This feature can, for instance, be used to construct a generic customer welcome message where the customer's name can be injected via a parameter. It's also possible to provide translations to different languages when creating a template to make it possible to reuse one template for different languages.

Template Management API Version 2

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

Accessing the Template Management API

The first step towards interacting with the Template Management API is to create an account on the Sinch Customer Dashboard. The next step is to create an Access Key under the Settings tab and note down the provided Key ID and Key Secret in a secure location. Also make sure to remember the Project ID since your template will be placed under the provided Project ID.

The Key ID and the Key Secret are then used in the following way to obtain a valid OAuth2 Access Token that will be used to authenticate towards the Template Management API.

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

The obtained Access Token is then used in the following way to interact with the Template Management API:

curl https://us.template.api.sinch.com/v1/projects/<Project ID>/templates -H "Authorization: Bearer <Access Token>"

Note that the obtained token above is only valid when interacting with the Template Management API in the US region. Another Access Token must be obtained from the FQDN eu.auth.sinch.com to interact with the Template Management API in the EU region(FQDN eu.template.api.sinch.com).

Download OpenAPI description
template.json
template.yaml
Overview
support at sinch

support@sinch.com

License

MIT

Languages
Servers
The {region} variable must be set to us, eu, or br, and it must match the region in which you created your Conversation API app.

https://{region}.template.api.sinch.com/

Templates V1

Version 1 endpoints for managing message templates. Currently maintained for existing users. Version 2 is recommended.

Operations

List all templates belonging to a project ID.

Request

Security
Basic or oAuth2
Path
project_idstringrequired

Required. The project ID.

curl -i -X GET \
  -u <username>:<password> \
  'https://us.template.api.sinch.com/v1/projects/{project_id}/templates'

Responses

A successful response.

Bodyapplication/json
templatesArray of objects(TODO: Pagination)
Response
application/json
{
  "templates": [
    { … }
  ]
}

Creates a template

Request

Security
Basic or oAuth2
Path
project_idstringrequired

Required. The project ID.

Bodyapplication/jsonrequired

Required. The template to create.

channelstring(typeChannel)
Enum ValueDescription
WHATSAPP

The WhatsApp channel.

RCS

The RCS channel.

SMS

The SMS channel.

MESSENGER

The Facebook Messenger channel.

VIBERBM

The Viber Business Messages channel.

INSTAGRAM

The Instagram channel.

TELEGRAM

The Telegram channel.

KAKAOTALK

The KakaoTalk channel.

APPLEBC

The Apple Messages for Business channel.

UNSPECIFIED

Unspecified channel.

create_timestring(date-time)

Timestamp when the template was created.

default_translationstringrequired

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.

descriptionstring

The description of the template.

idstring

The id of the template. Specify this yourself during creation otherwise we will generate an ID for you. This has to be unique for a given project.

translationsArray of objects(typeTemplateTranslation)required

List of translations for the template.

translations[].​contentstring

This is the definition of the template with the language specified in the language_code field.

translations[].​create_timestring(date-time)

Timestamp when the translation was created.

translations[].​language_codestring

The BCP-47 language code, such as en-US or sr-Latn. For more information, see https://www.unicode.org/reports/tr35/#Unicode_locale_identifier.

translations[].​update_timestring(date-time)

Timestamp of when the translation was updated.

translations[].​variablesArray of objects(typeTemplateVariable)

List of expected variables. Can be used for request validation.

translations[].​versionstring

The version of template.

update_timestring(date-time)

Timestamp when the template was updated.

curl -i -X POST \
  -u <username>:<password> \
  'https://us.template.api.sinch.com/v1/projects/{project_id}/templates' \
  -H 'Content-Type: application/json' \
  -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}.\" }}"
      }
    ]
  }'

Responses

A successful response.

Bodyapplication/json
channelstring(typeChannel)
Enum ValueDescription
WHATSAPP

The WhatsApp channel.

RCS

The RCS channel.

SMS

The SMS channel.

MESSENGER

The Facebook Messenger channel.

VIBERBM

The Viber Business Messages channel.

INSTAGRAM

The Instagram channel.

TELEGRAM

The Telegram channel.

KAKAOTALK

The KakaoTalk channel.

APPLEBC

The Apple Messages for Business channel.

UNSPECIFIED

Unspecified channel.

create_timestring(date-time)

Timestamp when the template was created.

default_translationstring

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.

descriptionstring

The description of the template.

idstring

The id of the template. Specify this yourself during creation otherwise we will generate an ID for you. This has to be unique for a given project.

translationsArray of objects(typeTemplateTranslation)

List of translations for the template.

update_timestring(date-time)

Timestamp when the template was updated.

Response
application/json
{
  "channel": "UNSPECIFIED",
  "create_time": "2019-08-24T14:15:22Z",
  "default_translation": "string",
  "description": "string",
  "id": "string",
  "translations": [
    { … }
  ],
  "update_time": "2019-08-24T14:15:22Z"
}

Updates a template.

Request

Security
Basic or oAuth2
Path
project_idstringrequired

Required. The project ID.

template_idstringrequired

The id of the template to be updated. Specified or automatically generated during template creation. Unique per project.

Query
update_maskArray of strings

The set of field mask paths.

Bodyapplication/jsonrequired

Required. The updated template.

channelstring(typeChannel)
Enum ValueDescription
WHATSAPP

The WhatsApp channel.

RCS

The RCS channel.

SMS

The SMS channel.

MESSENGER

The Facebook Messenger channel.

VIBERBM

The Viber Business Messages channel.

INSTAGRAM

The Instagram channel.

TELEGRAM

The Telegram channel.

KAKAOTALK

The KakaoTalk channel.

APPLEBC

The Apple Messages for Business channel.

UNSPECIFIED

Unspecified channel.

create_timestring(date-time)

Timestamp when the template was created.

default_translationstring

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.

descriptionstring

The description of the template.

idstring

The id of the template. Specify this yourself during creation otherwise we will generate an ID for you. This has to be unique for a given project.

translationsArray of objects(typeTemplateTranslation)

List of translations for the template.

update_timestring(date-time)

Timestamp when the template was updated.

curl -i -X PATCH \
  -u <username>:<password> \
  'https://us.template.api.sinch.com/v1/projects/{project_id}/templates/{template_id}?update_mask=string' \
  -H 'Content-Type: application/json' \
  -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}.\" }}"
      }
    ]
  }'

Responses

A successful response.

Bodyapplication/json
channelstring(typeChannel)
Enum ValueDescription
WHATSAPP

The WhatsApp channel.

RCS

The RCS channel.

SMS

The SMS channel.

MESSENGER

The Facebook Messenger channel.

VIBERBM

The Viber Business Messages channel.

INSTAGRAM

The Instagram channel.

TELEGRAM

The Telegram channel.

KAKAOTALK

The KakaoTalk channel.

APPLEBC

The Apple Messages for Business channel.

UNSPECIFIED

Unspecified channel.

create_timestring(date-time)

Timestamp when the template was created.

default_translationstring

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.

descriptionstring

The description of the template.

idstring

The id of the template. Specify this yourself during creation otherwise we will generate an ID for you. This has to be unique for a given project.

translationsArray of objects(typeTemplateTranslation)

List of translations for the template.

update_timestring(date-time)

Timestamp when the template was updated.

Response
application/json
{
  "channel": "UNSPECIFIED",
  "create_time": "2019-08-24T14:15:22Z",
  "default_translation": "string",
  "description": "string",
  "id": "string",
  "translations": [
    { … }
  ],
  "update_time": "2019-08-24T14:15:22Z"
}

Get a template

Request

Security
Basic or oAuth2
Path
project_idstringrequired

Required. The project ID.

template_idstringrequired

Required. The ID of the template to fetch.

curl -i -X GET \
  -u <username>:<password> \
  'https://us.template.api.sinch.com/v1/projects/{project_id}/templates/{template_id}'

Responses

A successful response.

Bodyapplication/json
channelstring(typeChannel)
Enum ValueDescription
WHATSAPP

The WhatsApp channel.

RCS

The RCS channel.

SMS

The SMS channel.

MESSENGER

The Facebook Messenger channel.

VIBERBM

The Viber Business Messages channel.

INSTAGRAM

The Instagram channel.

TELEGRAM

The Telegram channel.

KAKAOTALK

The KakaoTalk channel.

APPLEBC

The Apple Messages for Business channel.

UNSPECIFIED

Unspecified channel.

create_timestring(date-time)

Timestamp when the template was created.

default_translationstring

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.

descriptionstring

The description of the template.

idstring

The id of the template. Specify this yourself during creation otherwise we will generate an ID for you. This has to be unique for a given project.

translationsArray of objects(typeTemplateTranslation)

List of translations for the template.

update_timestring(date-time)

Timestamp when the template was updated.

Response
application/json
{
  "channel": "UNSPECIFIED",
  "create_time": "2019-08-24T14:15:22Z",
  "default_translation": "string",
  "description": "string",
  "id": "string",
  "translations": [
    { … }
  ],
  "update_time": "2019-08-24T14:15:22Z"
}

Delete a template.

Request

Security
Basic or oAuth2
Path
project_idstringrequired

Required. The project ID.

template_idstringrequired

Required. The ID of the template to fetch.

curl -i -X DELETE \
  -u <username>:<password> \
  'https://us.template.api.sinch.com/v1/projects/{project_id}/templates/{template_id}'

Responses

A successful response.

Bodyapplication/json
any
Response
application/json
null

Templates V2

Version 2 endpoints for managing message templates. Recommended version for all users. Includes strongly typed translations field (allowing for message definition using JSON structures also used in the send message request of the Conversation API), improved validation, and the ability to override omni-channel templates in favor of channel-specific templates (where available).

Operations