# Message Templates

Pre-set message templates allow you to create a message once and then have it on hand to send at any time. You can create and send message templates in the platform, mobile app, and the API.

## Use a template to send a message with the API

Templates can be sent by making a `POST` request to the <mark style="color:blue;">`/send`</mark> endpoint. All requests to this endpoint must contain both **recipient** and **content** information. When using a message template, the `templateId` is used as the content.

**Required request fields:**

* **Choose recipient(s):** (Must be one of the following)
  * `subscriberIds: number[]` - List of subscriber IDs of recipients. Messages can be sent to specific subscribers, with each subscriber assigned a unique `subscriberId`.
  * `subscribers: (number | string)[]`- List of recipient phone numbers or email addresses. A new subscriber will be created for new recipients that are not already subscribers on your account.
  * `allSubscribers: boolean` - Flag to indicate send message to all subscribers if `true`. When `allSubscribers` is set to `true`, no other recipient fields should be specified. Default value is `false`.
  * `groups: number[]` - List of group IDs of recipients. Messages can be sent to specific groups, with each group assigned a unique `groupId`.
  * `threadId: number` - Messages can be sent in reply to a thread, with each thread assigned a unique `threadId`.
* **Content:**
  * `templateId: number` - Messages can be saved as pre-set message templates for reuse with saved controlled templates on your account assigned a `templateId`.
* **Other fields:**
  * `linkId: number` - If a message contains a `linkId`, then this field is required. Links can be created with the [`/shortlinks` endpoint](#create-a-short-link).

### Send a message template with the API

{% stepper %}
{% step %}

### Indicate the recipient(s)

You can send a message to a phone number as a test. Here you would set the `subscribers` field to the recipient phone number.

```json
"subscribers": [1112223333]
```

{% endstep %}

{% step %}

### Indicate the template to be sent

Use the `templateId` field to indicate which template will be used.

```json
"templateId": 101
```

{% endstep %}

{% step %}

### Form API request

Create the API request to the `/send` endpoint. Remember to include the [Authorization](https://mobile-text-alerts.gitbook.io/developer-center#authentication) header.

```json
curl --location 'https://api.mobile-text-alerts.com/v3/send' \
--header 'Authorization: Bearer 89fa747a-e01b-5940-99c2-4e96fa996258' \
--data '{"subscribers": [1112223333],
        "templateId": 101
        }'
```

{% endstep %}

{% step %}

### Receive response

The API will return a message about the status of your request.

```json
{
  "data": {
    "messageId": "uuid",
    "totalSent": 1,
    "totalFailedInternationalRecipients": 0
  },
```

{% endstep %}
{% endstepper %}

<details>

<summary>Send Message <mark style="color:orange;background-color:yellow;">POST</mark> <code>/send</code></summary>

</details>

## Using Shortlinks with Controlled Templates

When sending or scheduling a message, the `/send` endpoint will compose the message body using the provided `templateId` for a controlled template and, if required by the template, a provided `linkId`. Links can be created with the `/shortlinks` endpoint.

<details>

<summary>Create Short Link <mark style="color:orange;background-color:yellow;">POST</mark> <code>/shortlinks</code></summary>

</details>

## Include personalization in a template

Mobile Text Alerts supports Liquid templates for message personalization. A template can include custom variables like `{{firstName}}`, which are replaced using per-recipient properties. This requires you to provide a `properties` object that maps each phone number to its corresponding data.

See [#properties-field-for-custom-variables-in-messages](https://developers.mobile-text-alerts.com/tutorials/send-an-sms-message#properties-field-for-custom-variables-in-messages "mention") to learn more.

## Templates API endpoints

### View all templates

You can call <mark style="color:green;background-color:green;">GET</mark> `/templates` to see all the available templates on your account:

<details>

<summary>List Templates <mark style="color:green;background-color:green;">GET</mark> <code>/templates</code></summary>

</details>

### View a specific template

To see the details on a specific template, you will need the `{id}` of the template. Then call <mark style="color:green;background-color:green;">GET</mark> `/templates/{id}` :

<details>

<summary>Get Template <mark style="color:green;background-color:green;">GET</mark> <code>/templates/{id}</code></summary>

</details>

### Update a specific template

To make changes to a specific template, you will need the `{id}` of the template. Then call <mark style="color:purple;background-color:purple;">PATCH</mark> `/templates/{id}` with the body containing the new template data, `message` is required.

**Example request:**

```json
curl --location --request PATCH 'https://api.mobile-text-alerts.com/v3/templates/123' \
--data '{
    "name": "Updated Template Name",
    "message": "This is an updated template message",
    "isMMS": true
}'
```

<details>

<summary>Update Template <mark style="color:purple;background-color:purple;">PATCH</mark> <code>/templates/{id}</code></summary>

</details>

### Delete a Template

To remove a specific template, you will need the `{id}` of the template, then call <mark style="color:red;background-color:red;">DELETE</mark> `/templates/{id}`

<details>

<summary>Delete Template <mark style="color:red;background-color:red;">DELETE</mark> <code>/templates/{id}</code></summary>

</details>

### Create a new template

When creating a new template, the `message` field is required to hold the content of the message.

**Example request:**

```json
curl --location 'https://api.mobile-text-alerts.com/v3/templates' \
--data '{
    "name": "New Template",
    "message": "This is a template message",
    "isMMS": true
}'
```

<details>

<summary>Create Template <mark style="color:orange;background-color:yellow;">POST</mark> <code>/templates</code></summary>

</details>

## Template-Only Sending

If your account is configured for template-only message sending, please use the Controlled Template endpoints below to view available templates:

<details>

<summary>List Controlled Templates <mark style="color:green;background-color:green;">GET</mark> <code>/controlled-templates</code></summary>

</details>

<details>

<summary>Get Controlled Template Endpoint <mark style="color:green;background-color:green;">GET</mark> <code>/controlled-templates/{controlledTemplateId}</code></summary>

</details>

### Template Examples

* [91 Sample Text Messages to Customers, Message Templates](https://mobile-text-alerts.com/articles/sample-text-messages-to-customers)
* [43 Auto Reply Text Message Examples (+ 3 Tips)](https://mobile-text-alerts.com/articles/auto-reply-text-message-examples)