# Managing 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](/docs/conversation/api-reference/template/section/overview).

The channel-specific templates are stored and managed by the channels, and are only referenced when sending through Conversation API. Currently, WhatsApp, [KakaoTalk](/docs/conversation/templates/channel-specific/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](https://dashboard.sinch.com/convapi/message-composer).

If you are unfamiliar with the Message Composer tool, we encourage you to view the [articles with the Message Composer tag](https://community.sinch.com/t5/Conversation-API/tkb-p/ConversationAPI/label-name/message%20composer) on the Sinch Community site. They provide more information about the tool, including [how to create an omni-channel template using the Message Composer](https://community.sinch.com/t5/Conversation-API/How-do-I-use-Message-Composer-to-create-omni-channel-message/ta-p/9890).

### Managing omni-channel templates using API calls

You can create, update, list, and delete omni-channel templates through the
[Template Management API](/docs/conversation/api-reference/template/section/overview), which is currently available in the following regions:

| Region | Host |
|  --- | --- |
| US | `https://us.template.api.sinch.com` |
| EU | `https://eu.template.api.sinch.com` |
| BR | `https://br.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 Build Dashboard](https://dashboard.sinch.com/settings/access-keys) 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:


```shell
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](#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](/docs/conversation/api-reference/conversation/messages/messages_sendmessage#messages/messages_sendmessage/t=request&path=correlation_id)
- 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

Note:
On January 31, 2026, Version 1 of the Template Management API (and the `v1` endpoint) will be fully replaced by the latest and more flexible Version 2 of the Template Management API (which uses the `v2` endpoint). Prior to that date, ensure that you have familiarized yourself with Version 2 of the Template Management API. Also ensure that any Template Management API calls in your system are updated to use the `v2` endpoint.


```shell
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:

| Field | Type | Description |
|  --- | --- | --- |
| description | string | Template description. |
| default_translation | string | A translation to use if none given when sending a template message. Must be a valid BCP-47 language code. |
| channel | string | The Template Management API can store messages in different formats. The omni-channel templates use `CONVERSATION` as channel. |
| translations | array of objects | List of translations for the template. |


Each translation object has the following properties:

| Field | Type | Description |
|  --- | --- | --- |
| language_code | string | The BCP-47 language code, such as `en-US` or `sr-Latn`. |
| version | string | The version of this template translation. |
| variables | array of objects | List of expected variables in the template translation. It's used to validate send template requests. |
| content | string | The 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:

| Field | Type | Description |
|  --- | --- | --- |
| key | string | The key with which the variable is referred to in the template content placeholders example, `<key>` |
| preview_value | string | A 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


```shell
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:


```json
{
  "$ref": "#/components/schemas/v2Template",
  "components": {
    "schemas": {
      "TemplateReference": {
        "type": "object",
        "title": "Template reference with concrete parameter values",
        "description": "The referenced template can be an omnichannel template stored in Conversation API Template Store as an AppMessage. You may also reference external channel-specific templates, such as a WhatsApp Business Template. Note that channel-specific template references are not supported when populating the `explicit_channel_omni_message` field.",
        "required": [
          "template_id"
        ],
        "properties": {
          "version": {
            "type": "string",
            "description": "Used to specify what version of a template to use. Required when using `omni_channel_override` and `omni_template` fields.\nThis will be used in conjunction with `language_code`. Note that, when referencing omni-channel templates using the [Sinch Customer Dashboard](https://dashboard.sinch.com/), the latest version of a given omni-template can be identified by populating this field with `latest`."
          },
          "language_code": {
            "description": "The BCP-47 language code, such as `en_US` or `sr_Latn`.\nFor more information, see http://www.unicode.org/reports/tr35/#Unicode_locale_identifier. English is the default `language_code`.\nNote that, while many API calls involving templates accept either the dashed format (`en-US`) or the underscored format (`en_US`), some channel specific templates (for example, WhatsApp channel-specific templates) only accept the underscored format. Note that this field is required for WhatsApp channel-specific templates.",
            "type": "string"
          },
          "parameters": {
            "description": "Required if the template has parameters. Concrete values must\nbe present for all defined parameters\nin the template. Parameters can be different for\ndifferent versions and/or languages of the template.",
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "template_id": {
            "description": "The ID of the template. Note that, in the case of WhatsApp channel-specific templates, this field must be populated by the name of the template.",
            "type": "string"
          }
        }
      },
      "ChannelTemplateOverride": {
        "type": [
          "object"
        ],
        "properties": {
          "template_reference": {
            "$ref": "#/components/schemas/TemplateReference"
          },
          "parameter_mappings": {
            "description": "A mapping between omni-template variables and the channel specific parameters.",
            "type": [
              "object"
            ],
            "additionalProperties": {
              "type": "string"
            }
          }
        }
      },
      "ChannelTemplateOverridesMap": {
        "description": "Field to override the omnichannel template by referring to a channel-specific template.\nThe key in the map must point to a valid conversation channel.\nCurrently only `WHATSAPP` and `KAKAOTALK` are supported",
        "type": "object",
        "additionalProperties": {
          "$ref": "#/components/schemas/ChannelTemplateOverride"
        }
      },
      "typeTemplateVariable": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "preview_value": {
            "type": "string"
          }
        }
      },
      "v2MessageCommonProps": {
        "type": "object",
        "properties": {
          "language_code": {
            "description": "The BCP-47 language code, such as `en-US` or `sr-Latn`. For more information,\nsee https://www.unicode.org/reports/tr35/#Unicode_locale_identifier.",
            "type": [
              "string"
            ]
          },
          "version": {
            "description": "The version of the translation.",
            "type": [
              "string"
            ],
            "example": "1"
          },
          "channel_template_overrides": {
            "$ref": "#/components/schemas/ChannelTemplateOverridesMap"
          },
          "variables": {
            "description": "List of expected variables. Can be used for request validation.",
            "type": [
              "array"
            ],
            "items": {
              "$ref": "#/components/schemas/typeTemplateVariable"
            }
          },
          "create_time": {
            "description": "Timestamp when the translation was created.",
            "type": [
              "string"
            ],
            "format": "date-time",
            "readOnly": true
          },
          "update_time": {
            "description": "Timestamp of when the translation was updated.",
            "type": [
              "string"
            ],
            "format": "date-time",
            "readOnly": true
          }
        }
      },
      "CallMessageField": {
        "description": "Message for triggering a call.",
        "type": "object",
        "title": "Call",
        "properties": {
          "call_message": {
            "title": "Call Message",
            "type": "object",
            "required": [
              "phone_number",
              "title"
            ],
            "properties": {
              "phone_number": {
                "description": "Phone number in E.164 with leading +.",
                "type": "string",
                "example": "+15551231234"
              },
              "title": {
                "description": "Title shown close to the phone number.\nThe title is clickable in some cases.",
                "type": "string",
                "example": "Message text"
              }
            }
          }
        }
      },
      "Coordinates": {
        "type": "object",
        "title": "Geographic coordinates",
        "required": [
          "latitude",
          "longitude"
        ],
        "properties": {
          "latitude": {
            "description": "The latitude.",
            "type": "number",
            "format": "float"
          },
          "longitude": {
            "description": "The longitude.",
            "type": "number",
            "format": "float"
          }
        }
      },
      "LocationMessageField": {
        "type": "object",
        "description": "Message containing geographic location.",
        "title": "Location",
        "properties": {
          "location_message": {
            "title": "Location Message",
            "type": "object",
            "required": [
              "coordinates",
              "title"
            ],
            "properties": {
              "coordinates": {
                "$ref": "#/components/schemas/Coordinates"
              },
              "label": {
                "description": "Label or name for the position.",
                "type": "string"
              },
              "title": {
                "description": "The title is shown close to the button or link that leads to a map showing the location. The title can be clickable in some cases.",
                "type": "string"
              }
            }
          }
        }
      },
      "TextMessageField": {
        "type": "object",
        "title": "Text",
        "description": "A message containing only text.",
        "properties": {
          "text_message": {
            "type": "object",
            "title": "Text Message",
            "required": [
              "text"
            ],
            "properties": {
              "text": {
                "description": "The text to be sent.",
                "type": "string"
              }
            }
          }
        }
      },
      "UrlMessageField": {
        "description": "A generic URL message.",
        "type": "object",
        "title": "URL",
        "properties": {
          "url_message": {
            "title": "URL Message",
            "type": "object",
            "required": [
              "title",
              "url"
            ],
            "properties": {
              "title": {
                "description": "The title shown close to the URL. The title can be clickable in some cases.",
                "type": "string"
              },
              "url": {
                "description": "The url to show.",
                "type": "string"
              }
            }
          }
        }
      },
      "CalendarMessageField": {
        "description": "Message containing details about a calendar event.",
        "type": "object",
        "title": "Calendar",
        "properties": {
          "calendar_message": {
            "title": "Calendar message",
            "type": "object",
            "required": [
              "title",
              "event_start",
              "event_end",
              "event_title",
              "fallback_url"
            ],
            "properties": {
              "title": {
                "description": "The title is shown close to the button that leads to open a user calendar.",
                "type": "string"
              },
              "event_start": {
                "description": "The timestamp defines start of a calendar event.",
                "type": "string",
                "format": "date-time",
                "example": "2025-11-30T10:00:00Z"
              },
              "event_end": {
                "description": "The timestamp defines end of a calendar event.",
                "type": "string",
                "format": "date-time",
                "example": "2025-11-30T11:00:00Z"
              },
              "event_title": {
                "description": "Title of a calendar event.",
                "type": "string"
              },
              "event_description": {
                "description": "Description of a calendar event.",
                "type": "string"
              },
              "fallback_url": {
                "description": "The URL that is opened when the user cannot open a calendar event directly or channel does not have support for this type.",
                "type": "string"
              }
            }
          }
        }
      },
      "ShareLocationMessageField": {
        "description": "Message requesting location from a user.",
        "type": "object",
        "title": "Request location",
        "properties": {
          "share_location_message": {
            "title": "Share Location Message",
            "type": "object",
            "required": [
              "title",
              "fallback_url"
            ],
            "properties": {
              "title": {
                "description": "The title is shown close to the button that leads to open a map to share a location.",
                "type": "string"
              },
              "fallback_url": {
                "description": "The URL that is opened when channel does not have support for this type.",
                "type": "string"
              }
            }
          }
        }
      },
      "choiceTypes": {
        "type": "object",
        "oneOf": [
          {
            "$ref": "#/components/schemas/CallMessageField"
          },
          {
            "$ref": "#/components/schemas/LocationMessageField"
          },
          {
            "$ref": "#/components/schemas/TextMessageField"
          },
          {
            "$ref": "#/components/schemas/UrlMessageField"
          },
          {
            "$ref": "#/components/schemas/CalendarMessageField"
          },
          {
            "$ref": "#/components/schemas/ShareLocationMessageField"
          }
        ]
      },
      "choiceCommonProps": {
        "type": "object",
        "properties": {
          "postback_data": {
            "description": "An optional field. This data will be returned in the ChoiceResponseMessage. The default is message_id_{text, title}."
          }
        }
      },
      "Choice": {
        "description": "A choice is an action the user can take such as buttons for quick replies or other call to actions.",
        "type": "object",
        "title": "Choice message",
        "allOf": [
          {
            "$ref": "#/components/schemas/choiceTypes"
          },
          {
            "$ref": "#/components/schemas/choiceCommonProps"
          }
        ]
      },
      "CardHeight": {
        "description": "You can set the desired size of the card in the message.",
        "type": "string",
        "x-enumDescriptions": {
          "UNSPECIFIED_HEIGHT": "The height of the card is unspecified.",
          "SHORT": "The shortest card height.",
          "MEDIUM": "Medium card height.",
          "TALL": "The tallest card height."
        },
        "enum": [
          "UNSPECIFIED_HEIGHT",
          "SHORT",
          "MEDIUM",
          "TALL"
        ]
      },
      "MediaProperties": {
        "title": "Media Properties",
        "type": "object",
        "required": [
          "url"
        ],
        "properties": {
          "thumbnail_url": {
            "type": "string",
            "description": "An optional parameter. Will be used where it is natively supported."
          },
          "url": {
            "description": "Url to the media file.",
            "type": "string"
          },
          "filename_override": {
            "description": "Overrides the media file name.",
            "type": "string"
          }
        }
      },
      "CardMessage": {
        "description": "Message containing text, media and choices.",
        "title": "Card Message",
        "type": "object",
        "properties": {
          "choices": {
            "description": "You may include choices in your Card Message. The number of choices is limited to 10.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Choice"
            }
          },
          "description": {
            "description": "This is an optional description field that is displayed below the title on the card.",
            "type": "string"
          },
          "height": {
            "$ref": "#/components/schemas/CardHeight"
          },
          "title": {
            "description": "The title of the card message.",
            "type": "string"
          },
          "media_message": {
            "type": "object",
            "description": "A message containing a media component.",
            "allOf": [
              {
                "$ref": "#/components/schemas/MediaProperties"
              }
            ]
          },
          "message_properties": {
            "type": "object",
            "description": "Optional additional properties.",
            "properties": {
              "whatsapp_header": {
                "description": "Optional. Sets the header for the footer of a WhatsApp reply button message, if there is no media in the message. Ignored for other channels. Ignored if not transcoded to a native WhatsApp message with reply buttons.",
                "type": "string"
              }
            }
          }
        }
      },
      "CardMessageField": {
        "description": "Field containing a Card Message",
        "type": "object",
        "title": "Card",
        "properties": {
          "card_message": {
            "$ref": "#/components/schemas/CardMessage"
          }
        }
      },
      "CarouselMessageField": {
        "description": "Message containing a list of cards often rendered horizontally on supported channels.",
        "type": "object",
        "title": "Carousel",
        "properties": {
          "carousel_message": {
            "title": "Carousel Message",
            "type": "object",
            "required": [
              "cards"
            ],
            "properties": {
              "cards": {
                "description": "A list of up to 10 cards.",
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/CardMessage"
                }
              },
              "choices": {
                "description": "Optional. Outer choices on the carousel level. The number of outer choices is limited to 3.",
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Choice"
                }
              }
            }
          }
        }
      },
      "Choices": {
        "type": "object",
        "properties": {
          "choices": {
            "type": "array",
            "description": "The number of choices is limited to 10.",
            "items": {
              "$ref": "#/components/schemas/Choice"
            }
          }
        }
      },
      "ChoiceMessagePropertiesField": {
        "type": "object",
        "title": "Properties",
        "description": "Additional properties for the message.",
        "properties": {
          "message_properties": {
            "type": "object",
            "properties": {
              "whatsapp_footer": {
                "description": "Optional. Sets the text for the footer of a WhatsApp reply button or URL button message. Ignored for other channels.",
                "type": "string"
              }
            }
          }
        }
      },
      "ChoiceMessageField": {
        "description": "Message containing choices/actions.",
        "type": "object",
        "title": "Choice",
        "properties": {
          "choice_message": {
            "title": "Choice Message",
            "type": "object",
            "required": [
              "choices"
            ],
            "allOf": [
              {
                "description": "A message containing choices."
              },
              {
                "$ref": "#/components/schemas/Choices"
              },
              {
                "$ref": "#/components/schemas/TextMessageField"
              },
              {
                "$ref": "#/components/schemas/ChoiceMessagePropertiesField"
              }
            ]
          }
        }
      },
      "MediaMessageField": {
        "type": "object",
        "title": "Media Message",
        "description": "A message containing a media component, such as an image, document, or video.",
        "properties": {
          "media_message": {
            "$ref": "#/components/schemas/MediaProperties"
          }
        }
      },
      "TemplateReferenceWithVersion": {
        "type": "object",
        "allOf": [
          {
            "required": [
              "version"
            ]
          },
          {
            "$ref": "#/components/schemas/TemplateReference"
          }
        ]
      },
      "TemplateMessageField": {
        "type": "object",
        "description": "Message referring to predefined template",
        "title": "Template Message",
        "properties": {
          "template_message": {
            "type": "object",
            "title": "Template Message",
            "properties": {
              "channel_template": {
                "description": "Optional. Channel specific template reference with parameters per channel.\nThe channel template if exists overrides the omnichannel template.\nAt least one of `channel_template` or `omni_template` needs to be present.\nThe key in the map must point to a valid conversation channel as\ndefined by the enum ConversationChannel.",
                "type": "object",
                "additionalProperties": {
                  "$ref": "#/components/schemas/TemplateReference"
                }
              },
              "omni_template": {
                "$ref": "#/components/schemas/TemplateReferenceWithVersion"
              }
            }
          }
        }
      },
      "ChoiceItem": {
        "type": "object",
        "title": "Choice",
        "description": "A message component for interactive messages, containing a choice.",
        "required": [
          "title"
        ],
        "properties": {
          "title": {
            "type": "string",
            "description": "Required parameter. Title for the choice item."
          },
          "description": {
            "type": "string",
            "description": "Optional parameter. The description (or subtitle) of this choice item."
          },
          "media": {
            "description": "Optional parameter. The media of this choice item.",
            "allOf": [
              {
                "$ref": "#/components/schemas/MediaProperties"
              }
            ]
          },
          "postback_data": {
            "type": "string",
            "description": "Optional parameter. Postback data that will be returned in the MO if the user selects this option."
          }
        }
      },
      "ProductItem": {
        "type": "object",
        "title": "Product",
        "description": "A message component for interactive messages, containing a product.",
        "required": [
          "id",
          "marketplace"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Required parameter. The ID for the product."
          },
          "marketplace": {
            "type": "string",
            "description": "Required parameter. The marketplace to which the product belongs.",
            "example": "FACEBOOK"
          },
          "quantity": {
            "type": "integer",
            "format": "int32",
            "description": "Output only. The quantity of the chosen product."
          },
          "item_price": {
            "type": "number",
            "format": "float",
            "description": "Output only. The price for one unit of the chosen product."
          },
          "currency": {
            "type": "string",
            "description": "Output only. The currency of the item_price."
          }
        }
      },
      "ListItem": {
        "type": "object",
        "title": "List Item",
        "description": "Item containing either choiceItem or ProductItem",
        "oneOf": [
          {
            "required": [
              "choice"
            ],
            "type": "object",
            "properties": {
              "choice": {
                "$ref": "#/components/schemas/ChoiceItem"
              }
            },
            "title": "Choice"
          },
          {
            "required": [
              "product"
            ],
            "type": "object",
            "properties": {
              "product": {
                "$ref": "#/components/schemas/ProductItem"
              }
            },
            "title": "Product"
          }
        ]
      },
      "ListSection": {
        "type": "object",
        "title": "List Section",
        "description": "Section for interactive WhatsApp messages containing ListItem",
        "required": [
          "items"
        ],
        "properties": {
          "title": {
            "description": "Optional parameter. Title for list section.",
            "type": "string"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ListItem"
            }
          }
        }
      },
      "ListMessageField": {
        "type": "object",
        "title": "List",
        "description": "A message containing a list of options to choose from. All items must be of the same type.",
        "properties": {
          "list_message": {
            "title": "List Message",
            "type": "object",
            "required": [
              "title",
              "sections"
            ],
            "properties": {
              "title": {
                "description": "A title for the message that is displayed near the products or choices.",
                "type": "string"
              },
              "description": {
                "description": "This is an optional field, containing a description for the message.",
                "type": "string"
              },
              "media": {
                "$ref": "#/components/schemas/MediaProperties"
              },
              "sections": {
                "description": "List of ListSection objects containing choices to be presented in the list message.",
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ListSection"
                }
              },
              "message_properties": {
                "description": "Additional properties for the message. Required if sending a product list message.",
                "properties": {
                  "catalog_id": {
                    "description": "Required if sending a product list message. The ID of the catalog to which the products belong.",
                    "type": "string"
                  },
                  "menu": {
                    "description": "Optional. Sets the text for the menu of a choice list message.",
                    "type": "string"
                  },
                  "whatsapp_header": {
                    "description": "Optional. Sets the text for the header of a WhatsApp choice list message. Ignored for other channels.",
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "NameInfo": {
        "type": "object",
        "title": "Name of the contact",
        "description": "Name information of the contact.",
        "required": [
          "full_name"
        ],
        "properties": {
          "full_name": {
            "description": "Full name of the contact",
            "type": "string"
          },
          "first_name": {
            "description": "First name.",
            "type": "string"
          },
          "last_name": {
            "description": "Last name.",
            "type": "string"
          },
          "middle_name": {
            "description": "Middle name.",
            "type": "string"
          },
          "prefix": {
            "description": "Prefix before the name. e.g. Mr, Mrs, Dr etc.",
            "type": "string"
          },
          "suffix": {
            "description": "Suffix after the name.",
            "type": "string"
          }
        }
      },
      "PhoneNumberInfo": {
        "type": "object",
        "title": "Phone number",
        "description": "Phone numbers of the contact.",
        "required": [
          "phone_number"
        ],
        "properties": {
          "phone_number": {
            "description": "Phone number with country code included.",
            "type": "string"
          },
          "type": {
            "description": "Phone number type, e.g. WORK or HOME.",
            "type": "string"
          }
        }
      },
      "AddressInfo": {
        "type": "object",
        "title": "Address information",
        "description": "Physical addresses of the contact.",
        "properties": {
          "city": {
            "description": "City Name",
            "type": "string"
          },
          "country": {
            "description": "Country Name",
            "type": "string"
          },
          "state": {
            "description": "Name of a state or region of a country.",
            "type": "string"
          },
          "zip": {
            "description": "Zip/postal code",
            "type": "string"
          },
          "type": {
            "description": "Address type, e.g. WORK or HOME",
            "type": "string"
          },
          "country_code": {
            "description": "Two letter country code.",
            "type": "string"
          }
        }
      },
      "EmailInfo": {
        "type": "object",
        "title": "Email information",
        "description": "Email addresses of the contact.",
        "required": [
          "email_address"
        ],
        "properties": {
          "email_address": {
            "description": "Email address.",
            "type": "string"
          },
          "type": {
            "description": "Email address type. e.g. WORK or HOME.",
            "type": "string"
          }
        }
      },
      "OrganizationInfo": {
        "type": "object",
        "title": "Organization information",
        "description": "Organization information of the contact.",
        "properties": {
          "company": {
            "description": "Company name",
            "type": "string"
          },
          "department": {
            "description": "Department at the company",
            "type": "string"
          },
          "title": {
            "description": "Corporate title, e.g. Software engineer",
            "type": "string"
          }
        }
      },
      "UrlInfo": {
        "type": "object",
        "title": "URL Info",
        "description": "A URL/website",
        "required": [
          "url"
        ],
        "properties": {
          "url": {
            "description": "The URL to be referenced",
            "type": "string"
          },
          "type": {
            "description": "Optional. URL type, e.g. Org or Social",
            "type": "string"
          }
        }
      },
      "ContactInfoMessageField": {
        "type": "object",
        "description": "Message containing contact information.",
        "title": "Contact Info",
        "properties": {
          "contact_info_message": {
            "title": "Contact Info Message",
            "type": "object",
            "required": [
              "name",
              "phone_numbers"
            ],
            "properties": {
              "name": {
                "$ref": "#/components/schemas/NameInfo"
              },
              "phone_numbers": {
                "description": "Phone numbers of the contact",
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PhoneNumberInfo"
                }
              },
              "addresses": {
                "description": "Physical addresses of the contact",
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AddressInfo"
                }
              },
              "email_addresses": {
                "description": "Email addresses of the contact",
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/EmailInfo"
                }
              },
              "organization": {
                "$ref": "#/components/schemas/OrganizationInfo"
              },
              "urls": {
                "description": "URLs/websites associated with the contact",
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/UrlInfo"
                }
              },
              "birthday": {
                "description": "Date of birth in YYYY-MM-DD format.",
                "type": "string"
              }
            }
          }
        }
      },
      "v2MessageTypes": {
        "type": "object",
        "description": "Must be one of the following: [text_message, card_message, carousel_message,\nchoice_message, location_message, media_message, template_message, list_message]",
        "oneOf": [
          {
            "$ref": "#/components/schemas/CardMessageField"
          },
          {
            "$ref": "#/components/schemas/CarouselMessageField"
          },
          {
            "$ref": "#/components/schemas/ChoiceMessageField"
          },
          {
            "$ref": "#/components/schemas/LocationMessageField"
          },
          {
            "$ref": "#/components/schemas/MediaMessageField"
          },
          {
            "$ref": "#/components/schemas/TemplateMessageField"
          },
          {
            "$ref": "#/components/schemas/TextMessageField"
          },
          {
            "$ref": "#/components/schemas/ListMessageField"
          },
          {
            "$ref": "#/components/schemas/ContactInfoMessageField"
          }
        ]
      },
      "v2TemplateTranslation": {
        "type": "object",
        "required": [
          "language_code",
          "message"
        ],
        "allOf": [
          {
            "$ref": "#/components/schemas/v2MessageCommonProps"
          },
          {
            "$ref": "#/components/schemas/v2MessageTypes"
          }
        ]
      },
      "v2Template": {
        "type": [
          "object"
        ],
        "properties": {
          "id": {
            "description": "The id of the template. Specify this yourself during creation.\nOtherwise, we will generate an ID for you. This must be unique\nfor a given project.",
            "type": [
              "string"
            ],
            "example": "id_string"
          },
          "description": {
            "description": "The description of the template.",
            "type": [
              "string"
            ],
            "example": "Template description"
          },
          "version": {
            "description": "The version of the template. While creating a template, this will be defaulted to 1.\nWhen updating a template, you must supply the latest version of the template in order for the update to be successful.",
            "type": [
              "integer"
            ],
            "example": 1
          },
          "default_translation": {
            "type": [
              "string"
            ],
            "description": "The default translation to use if not specified.\nSpecified as a BCP-47 `language_code` and the `language_code` must exist\nin the translations list.",
            "example": "en-US"
          },
          "translations": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/v2TemplateTranslation"
            }
          },
          "create_time": {
            "description": "Timestamp of when the template was created.",
            "type": [
              "string"
            ],
            "format": "date-time",
            "readOnly": true
          },
          "update_time": {
            "description": "Timestamp when the template was updated.",
            "type": [
              "string"
            ],
            "format": "date-time",
            "readOnly": true
          }
        }
      }
    }
  }
}
```

### 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](/docs/conversation/message-types/#sending-omni-channel-templates).

## Channel-specific templates

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

Currently, WhatsApp, [KakaoTalk](/docs/conversation/templates/channel-specific/kakaotalk), and WeChat are the only channels that have channel-specific templates.

- WhatsApp templates can be created using either the [Sinch Build Dashboard](https://dashboard.sinch.com/) or the [Provisioning API](/docs/provisioning-api/api-reference/provisioning-api/whatsapp-templates/templatescontroller_createtemplate_v1). They are then uploaded to and approved by Facebook, and are required to send messages outside of the customer care session.
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](/docs/provisioning-api/api-reference/provisioning-api/whatsapp-templates/templatescontroller_updatetemplate_v1) 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](/docs/conversation/message-types/#sending-channel-specific-templates).

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