# 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)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.mobile-text-alerts.com/tutorials/message-sending/message-templates.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.