Skip to content
Conversation API/API reference/
/
Updates a template.

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

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

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/v2/projects/{project_id}/templates'

Responses

A successful response.

Bodyapplication/json
templatesArray of objects(v2Template)
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.

idstring

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

Example: "id_string"
descriptionstring

The description of the template.

Example: "Template description"
versioninteger

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.

Example: 1
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.

Example: "en-US"
translationsArray of Card (object) or Carousel (object) or Choice (object) or Location (object) or Media Message (object) or Template Message (object) or Text (object) or List (object) or Contact Info (object)(v2TemplateTranslation)required
One of:

Must be one of the following: [text_message, card_message, carousel_message, choice_message, location_message, media_message, template_message, list_message]

translations[].​card_messageobject(CardMessage)

Message containing text, media and choices.

translations[].​language_codestringrequired

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[].​versionstring

The version of the translation.

Example: "1"
translations[].​channel_template_overridesobject(ChannelTemplateOverridesMap)

Field to override the omnichannel template by referring to a channel-specific template. The key in the map must point to a valid conversation channel. Currently only WHATSAPP and KAKAOTALK are supported

translations[].​variablesArray of objects(typeTemplateVariable)

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

translations[].​create_timestring(date-time)

Timestamp when the translation was created.

translations[].​update_timestring(date-time)

Timestamp of when the translation was updated.

curl -i -X POST \
  -u <username>:<password> \
  'https://us.template.api.sinch.com/v2/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-US",
    "translations": [
      {
        "language_code": "en-US",
        "version": "1",
        "variables": [
          {
            "key": "name",
            "preview_value": "Mr Jones"
          }
        ],
        "text_message": {
          "text": "Hi ${name}"
        },
        "channel_template_overrides": {
          "WHATSAPP": {
            "template_reference": {
              "template_id": "<referenced template id>",
              "version": 1,
              "language_code": "en-US",
              "parameters": {
                "body[1]text": "defaultValue"
              }
            },
            "parameter_mappings": {
              "body[1]text": "name"
            }
          }
        }
      }
    ]
  }'

Responses

A successful response.

Bodyapplication/json
idstring

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

Example: "id_string"
descriptionstring

The description of the template.

Example: "Template description"
versioninteger

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.

Example: 1
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.

Example: "en-US"
translationsArray of Card (object) or Carousel (object) or Choice (object) or Location (object) or Media Message (object) or Template Message (object) or Text (object) or List (object) or Contact Info (object)(v2TemplateTranslation)
create_timestring(date-time)read-only

Timestamp of when the template was created.

update_timestring(date-time)read-only

Timestamp when the template was updated.

Response
application/json
{
  "id": "id_string",
  "description": "Template description",
  "version": 1,
  "default_translation": "en-US",
  "translations": [
    { … }
  ],
  "create_time": "2019-08-24T14:15:22Z",
  "update_time": "2019-08-24T14:15:22Z"
}

List translations for a template

Request

Security
Basic or oAuth2
Path
project_idstringrequired

Required. The project ID.

template_idstringrequired

Required. The ID of the template to fetch.

Query
language_codestring

Optional. The translation's language code.

translation_versionstring

Optional. The translation's version.

curl -i -X GET \
  -u <username>:<password> \
  'https://us.template.api.sinch.com/v2/projects/{project_id}/templates/{template_id}/translations?language_code=string&translation_version=string'

Responses

A successful response.

Bodyapplication/json
translationsArray of Card (object) or Carousel (object) or Choice (object) or Location (object) or Media Message (object) or Template Message (object) or Text (object) or List (object) or Contact Info (object)(v2TemplateTranslation)
Response
application/json
{
  "translations": [
    { … }
  ]
}

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.

Bodyapplication/jsonrequired

Required. The updated template.

idstringrequired

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

Example: "id_string"
descriptionstring

The description of the template.

Example: "Template description"
versionintegerrequired

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.

Example: 1
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.

Example: "en-US"
translationsArray of Card (object) or Carousel (object) or Choice (object) or Location (object) or Media Message (object) or Template Message (object) or Text (object) or List (object) or Contact Info (object)(v2TemplateTranslation)
curl -i -X PUT \
  -u <username>:<password> \
  'https://us.template.api.sinch.com/v2/projects/{project_id}/templates/{template_id}' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "<template id>",
    "description": "English text template with one parameter using Conversation API generic format.",
    "version": 1,
    "default_translation": "en-US",
    "translations": [
      {
        "language_code": "en-US",
        "version": "1",
        "variables": [
          {
            "key": "name",
            "preview_value": "Mr Jones"
          }
        ],
        "text_message": {
          "text": "Hi ${name}"
        },
        "channel_template_overrides": {
          "WHATSAPP": {
            "template_reference": {
              "template_id": "<referenced template id>",
              "version": 1,
              "language_code": "en-US",
              "parameters": {
                "body[1]text": "defaultValue"
              }
            },
            "parameter_mappings": {
              "body[1]text": "name"
            }
          }
        }
      }
    ]
  }'

Responses

A successful response.

Bodyapplication/json
idstring

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

Example: "id_string"
descriptionstring

The description of the template.

Example: "Template description"
versioninteger

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.

Example: 1
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.

Example: "en-US"
translationsArray of Card (object) or Carousel (object) or Choice (object) or Location (object) or Media Message (object) or Template Message (object) or Text (object) or List (object) or Contact Info (object)(v2TemplateTranslation)
create_timestring(date-time)read-only

Timestamp of when the template was created.

update_timestring(date-time)read-only

Timestamp when the template was updated.

Response
application/json
{
  "id": "id_string",
  "description": "Template description",
  "version": 1,
  "default_translation": "en-US",
  "translations": [
    { … }
  ],
  "create_time": "2019-08-24T14:15:22Z",
  "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/v2/projects/{project_id}/templates/{template_id}'

Responses

A successful response.

Bodyapplication/json
idstring

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

Example: "id_string"
descriptionstring

The description of the template.

Example: "Template description"
versioninteger

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.

Example: 1
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.

Example: "en-US"
translationsArray of Card (object) or Carousel (object) or Choice (object) or Location (object) or Media Message (object) or Template Message (object) or Text (object) or List (object) or Contact Info (object)(v2TemplateTranslation)
create_timestring(date-time)read-only

Timestamp of when the template was created.

update_timestring(date-time)read-only

Timestamp when the template was updated.

Response
application/json
{
  "id": "id_string",
  "description": "Template description",
  "version": 1,
  "default_translation": "en-US",
  "translations": [
    { … }
  ],
  "create_time": "2019-08-24T14:15:22Z",
  "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 delete.

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

Responses

A successful response.

Bodyapplication/json
any
Response
application/json
null