---
title: "Create a message template"
method: POST
path: "/v1/projects/{project_id}/message_templates"
tags: ["MessageTemplate"]
---

# Create a message template

`POST /v1/projects/{project_id}/message_templates`

## Request

- Base URL: `https://api.telerivet.com`
- URL: `https://api.telerivet.com/v1/projects/{project_id}/message_templates`
- Auth: one of:
  - HTTP basic
  - OAuth 2 (authorization code, authorization URL `https://telerivet.com/oauth/authorize`, token URL `https://api.telerivet.com/oauth/token`)

Creates a new message template that can be used when composing or scheduling messages.

## Path parameters

- `project_id` string, required

## Request body

- object
  - `name` string, required: Name of the template (max 127 characters)
  - `content` string, required: Content of the message template (max 2000 characters)
  - `track_clicks` boolean: If true, URLs in the content will be replaced with short links that track clicks. Requires a plan with click tracking enabled.
  - `short_link_params` object: If `track_clicks` is true, `short_link_params` may be used to specify custom parameters for each short link.
  - `media` object[]: Array of media attachments to include when sending messages with this template. Alternatively, you can use the `media_urls` parameter with an array of URL strings.
    - `url` string: URL of the media file. Required unless file_id is provided. Use a https:// or http:// URL for media files that are already accessible via the internet. For media files that are not already accessible via the internet or uploaded as a stored file, the URL may be a data URI with the file data encoded via Base64 (e.g. "data:image/png;base64,..."), with a maximum decoded file size of 5 MB. Telerivet will automatically store this file in your project.
    - `file_id` string: ID of a previously uploaded stored file (see [project.uploadFile](#Project.uploadFile)). If file_id is provided, url is not required.
    - `type` string: MIME type of the media file (e.g. image/png). if not provided, Telerivet will attempt to determine the MIME type automatically from the extension of the filename or URL path component. Ignored if file_id is provided. To attach the Contact Card of the route that sends the message, use a media item with only `type` set to `route_vcard`.
    - `filename` string: Original filename of the media. Ignored if file_id is provided.
  - `route_params` object: Route-specific parameters to use when sending messages with this template. When sending messages via chat apps such as WhatsApp, the route_params parameter can be used to send messages with app-specific features such as quick replies and link buttons. For more details, see Route-Specific Parameters.
  - `variants` object[]: Alternative message bodies to use instead of the default message body when their conditions match, when sending messages with this template. Allows sending different message bodies depending on the route that sends the message, or the contact that the message is sent to. Each variant has conditions and its own message body. When each message is sent, the first variant whose conditions match is used instead of the default message body; if no variant matches, the default message body is used. A variant replaces the entire message body: content, media, route_params, track_clicks and short_link_params that are not specified in the variant are empty, not inherited from the default message body. Conditions are evaluated when the message is sent by a particular basic route, and can use the same variables as outgoing message content: contact variables such as [[contact.name]] and [[contact.vars.\*]], [[to_number]], [[time]], [[project.\*]], and variables of the basic route sending the message: [[phone.type]] (e.g. whatsapp), [[phone.id]], [[phone.vars.\*]], and [[phone.supports_quick_replies]], [[phone.supports_link_button]], [[phone.supports_native_attachments]] (1 if the route supports the feature, otherwise 0). Variables may include filters, e.g. [[contact.vars.language|default:"en"]]. For all available variables, see the [Variable Reference](https://telerivet.com/api/rest#variables). For A/B testing, a variant can have a random split (split_percent) so that it is only used for a random percentage of recipients, e.g. a single variant with split_percent 50 is used for about half of the recipients, and the default message body for the others. A random split can be combined with other conditions to run separate A/B tests for different routes or contacts. Since the first matching variant is used, list more specific variants before more general ones. For example, a variant with a condition `[[contact.vars.language]] is 'fr'` and split_percent 50 must be listed before a variant with only the condition `[[contact.vars.language]] is 'fr'`. Up to 10 variants are supported, each with up to 5 conditions.
    - `conditions` object[]: Conditions for using this variant (up to 5). Required unless the variant has a `split_percent`.
      - `variable` string: Variable to compare (required except when condition type is `contact_is_in_group` or `contact_not_in_group`), surrounded by double square brackets, e.g. `[[phone.type]]` or `[[contact.vars.lang]]`
      - `type` string, required: Type of condition
      - `value` string, required: Value to compare with the variable, or the group name if the condition type is `contact_is_in_group` or `contact_not_in_group`
    - `op` string: Operator to join multiple conditions: `and` (default) or `or`. If `split_percent` is specified, `or` is not supported.
    - `split_percent` integer: For A/B testing, the approximate percentage of recipients (1-100) randomly selected for this variant. Each variant with a `split_percent` is used for a separate random group of recipients, and recipients not selected for any variant receive the default message body (e.g. a single variant with a `split_percent` of 50 is used for about half of the recipients). Recipients are assigned to groups deterministically, so each contact is in the same group for all messages in the same broadcast or campaign. The total `split_percent` of all variants with the same conditions can be at most 100. If `split_percent` is omitted, the variant is used for all recipients that match its conditions.
    - `content` string: Content of the message when this variant is used
    - `media` object[]: Array of media attachments when this variant is used (same format as the `media` parameter)
    - `route_params` object: Route-specific parameters when this variant is used
    - `track_clicks` boolean: Whether to shorten links and track link clicks when this variant is used
    - `short_link_params` object: Parameters for short links when `track_clicks` is enabled (same format as the `short_link_params` parameter)
  - `solution_id` string: ID of the solution that this message template is part of, if applicable

## Response `200`

Successful response

- MessageTemplate: Represents a reusable message template that can be used when composing or scheduling messages. Message templates can include placeholder variables using double square brackets (e.g. `[[contact.name]]`) that are replaced with actual values when the message is sent. For available variables, see Variable Reference. The double square brackets may also include [filters](https://telerivet.com/api/rules_engine#filters) to transform variables, such as to set a default value. Templates synchronized from a WhatsApp Business Account are read-only and cannot be modified or deleted via the API. (When using Telerivet to send messages via a WhatsApp route, Telerivet tries to match the content of each outgoing message to one of these WhatsApp message templates. If a template matches, Telerivet sends a WhatsApp template message instead of a session message.)
  - `id` string: ID of the message template
  - `name` string: Name of the template (max 127 characters)
  - `content` string: Content of the message template (max 2000 characters)
  - `track_clicks` boolean: If true, URLs in the content will be replaced with short links that track clicks when the template is used
  - `readonly` boolean: True if the template cannot be modified or deleted (i.e., it was synchronized from a WhatsApp Business Account)
  - `short_link_params` object, nullable: Custom parameters for short links (only if track_clicks is true)
  - `media` object[], nullable: Array of media attachments to include when sending messages with this template. When updating this field, each item is an object with a `url` or `file_id` property (and optionally `type` and `filename`), in the same format as the `media` parameter of project.sendMessage.
    - `url` string: URL of the media file. Note: For files stored by Telerivet (including uploaded files and incoming media attachments), the URL is temporary and may not be valid for more than 1 day.
    - `type` string: MIME type of the media file, or `route_vcard` for the Contact Card of the sending route in a message that has not been sent yet (in which case the other properties are null)
    - `filename` string: Original filename
    - `size` integer: File size in bytes
    - `file_id` string: ID of the stored file, if applicable
  - `route_params` object, nullable: Route-specific parameters to use when sending messages with this template. When sending messages via chat apps such as WhatsApp, the route_params parameter can be used to send messages with app-specific features such as quick replies and link buttons. For more details, see Route-Specific Parameters.
  - `variants` object[], nullable: Alternative message bodies to use instead of the default message body when their conditions match, when sending messages with this template. Allows sending different message bodies depending on the route that sends the message, or the contact that the message is sent to. Each variant has conditions and its own message body. When each message is sent, the first variant whose conditions match is used instead of the default message body; if no variant matches, the default message body is used. A variant replaces the entire message body: content, media, route_params, track_clicks and short_link_params that are not specified in the variant are empty, not inherited from the default message body. Conditions are evaluated when the message is sent by a particular basic route, and can use the same variables as outgoing message content: contact variables such as [[contact.name]] and [[contact.vars.\*]], [[to_number]], [[time]], [[project.\*]], and variables of the basic route sending the message: [[phone.type]] (e.g. whatsapp), [[phone.id]], [[phone.vars.\*]], and [[phone.supports_quick_replies]], [[phone.supports_link_button]], [[phone.supports_native_attachments]] (1 if the route supports the feature, otherwise 0). Variables may include filters, e.g. [[contact.vars.language|default:"en"]]. For all available variables, see the [Variable Reference](https://telerivet.com/api/rest#variables). For A/B testing, a variant can have a random split (split_percent) so that it is only used for a random percentage of recipients, e.g. a single variant with split_percent 50 is used for about half of the recipients, and the default message body for the others. A random split can be combined with other conditions to run separate A/B tests for different routes or contacts. Since the first matching variant is used, list more specific variants before more general ones. For example, a variant with a condition `[[contact.vars.language]] is 'fr'` and split_percent 50 must be listed before a variant with only the condition `[[contact.vars.language]] is 'fr'`. Up to 10 variants are supported, each with up to 5 conditions.
    - `conditions` object[]: Conditions for using this variant (up to 5). Required unless the variant has a `split_percent`.
      - `variable` string: Variable to compare (required except when condition type is `contact_is_in_group` or `contact_not_in_group`), surrounded by double square brackets, e.g. `[[phone.type]]` or `[[contact.vars.lang]]`
      - `type` string, required: Type of condition
      - `value` string, required: Value to compare with the variable, or the group name if the condition type is `contact_is_in_group` or `contact_not_in_group`
    - `op` string: Operator to join multiple conditions: `and` (default) or `or`. If `split_percent` is specified, `or` is not supported.
    - `split_percent` integer: For A/B testing, the approximate percentage of recipients (1-100) randomly selected for this variant. Each variant with a `split_percent` is used for a separate random group of recipients, and recipients not selected for any variant receive the default message body (e.g. a single variant with a `split_percent` of 50 is used for about half of the recipients). Recipients are assigned to groups deterministically, so each contact is in the same group for all messages in the same broadcast or campaign. The total `split_percent` of all variants with the same conditions can be at most 100. If `split_percent` is omitted, the variant is used for all recipients that match its conditions.
    - `content` string: Content of the message when this variant is used
    - `media` object[]: Array of media attachments when this variant is used (same format as the `media` parameter)
    - `route_params` object: Route-specific parameters when this variant is used
    - `track_clicks` boolean: Whether to shorten links and track link clicks when this variant is used
    - `short_link_params` object: Parameters for short links when `track_clicks` is enabled (same format as the `short_link_params` parameter)
  - `waba_id` string, nullable: ID of the WhatsApp Business Account that this template is associated with (only present for WhatsApp templates)
  - `whatsapp_template` object, nullable: For templates synchronized from a WhatsApp Business Account, contains the full template data from WhatsApp with properties including `id`, `name`, `language`, `status`, `category`, and `components`. The full format is defined in the [WhatsApp Template API documentation](https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/template-api#get-version-template-id). Only present for WhatsApp templates.
  - `time_created` integer: Time the template was created in Telerivet
  - `time_updated` integer: Time the template was last updated
  - `vars` object: Custom variables stored for this template. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.
  - `solution_id` string, nullable: ID of the solution that this message template belongs to, if any
  - `project_id` string: ID of the project this template belongs to

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key or Bearer token
- `404`: Resource not found

---

[API](https://skmtc.dev/telerivet/apis/telerivet-api.md) · [All operations](https://skmtc.dev/telerivet/apis/telerivet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/telerivet/apis/telerivet-api/revisions/4e14b1c8d917?raw)