Message Templates

Learn how to use Message Templates when calling the Mobile Text Alerts API

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 in a message by sending a POST request to the /send endpoint. All requests to this endpoint must contain both recipient and content information. When using a message template, the templateId will be 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.

Send a message template with the API

1

Indicate the recipients(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.

"subscribers": [1112223333]

2

Indicate the template to be sent

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

"templateId": 101

3

Form API request

Create the API request to the /send endpoint. Remember to include Authorization header.

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

4

Receive response

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

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

Send Message POST /send

Send Message from API

post

Authorizations

Body

groupsnumber[]Optional

subscribersone of[]Optional

subscriberIdsnumber[]Optional

allSubscribersbooleanOptional

excludedGroupIdsnumber[]Optional

threadIdnumberOptional

messagestringRequired

imagestringOptional

rehostbooleanOptional

externalIdstringOptional

scheduledDatestringOptional

headerstringOptional

footerstringOptional

propertiesobjectOptional

isMMSbooleanOptional

repeatall ofOptional

linkClickDaysnumberOptional

templateIdnumberOptional

linkIdnumberOptional

longcodeIdnumberOptional

eventIdstringOptional

skipHeaderFooterbooleanOptional

addPlaceholderbooleanOptional

sourcestring · enumOptionalAvailable options:

userSignaturestringOptional

tagsobjectOptional

poolIdstringOptional

userIdnumberOptional

senderNamestringOptional

customRepeatFrequencyTypenumber | nullableOptional

customRepeatFrequencynumber | nullableOptional

customRepeatDaysall ofOptional

Used when a reference can be null

customEndMessageTypenumber | nullableOptional

customEndMessageDatestring | nullableOptional

customEndMessageOccurrencesnumber | nullableOptional

Responses

application/json

all ofOptional

application/json

application/json

application/json

application/json

application/json

post

HTTPcURLJavaScriptPython

POST /v3/send HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer apiKey
Content-Type: application/json
Accept: */*
Content-Length: 1032

{
  "groups": [
    1
  ],
  "subscribers": [
    1
  ],
  "subscriberIds": [
    1
  ],
  "allSubscribers": true,
  "excludedGroupIds": [
    1
  ],
  "threadId": 1,
  "message": "text",
  "image": "text",
  "rehost": true,
  "externalId": "text",
  "scheduledDate": "text",
  "header": "text",
  "footer": "text",
  "properties": {
    "ANY_ADDITIONAL_PROPERTY": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    }
  },
  "isMMS": true,
  "repeat": {
    "monday": true,
    "tuesday": true,
    "wednesday": true,
    "thursday": true,
    "friday": true,
    "saturday": true,
    "sunday": true,
    "type": "week",
    "frequency": -1,
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "linkClickDays": 1,
  "templateId": 1,
  "linkId": 1,
  "longcodeId": 1,
  "eventId": "text",
  "skipHeaderFooter": true,
  "addPlaceholder": true,
  "source": "control-panel",
  "userSignature": "text",
  "tags": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "poolId": "text",
  "userId": 1,
  "senderName": "text",
  "customRepeatFrequencyType": 1,
  "customRepeatFrequency": 1,
  "customRepeatDays": {
    "monday": true,
    "tuesday": true,
    "wednesday": true,
    "thursday": true,
    "friday": true,
    "saturday": true,
    "sunday": true
  },
  "customEndMessageType": 1,
  "customEndMessageDate": "text",
  "customEndMessageOccurrences": 1
}

{
  "statusCode": "MTANoLinkedAccountError",
  "success": true,
  "error": "text",
  "message": "text",
  "data": {
    "messageId": "text",
    "totalSent": 1,
    "totalFailedInternationalRecipients": 1,
    "outboundIds": [
      1
    ]
  }
}

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.

Create Short Link POST /shortlinks

Create Link

post

Authorizations

Body

longUrlstringRequired

trackingEnabledbooleanOptional

isMMSbooleanOptional

ageCheckbooleanOptional

tagsstring[]Optional

isWebinarbooleanOptional

Responses

application/json

all ofOptional

application/json

application/json

application/json

application/json

post

HTTPcURLJavaScriptPython

POST /v3/links/shortlinks HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer apiKey
Content-Type: application/json
Accept: */*
Content-Length: 103

{
  "longUrl": "text",
  "trackingEnabled": true,
  "isMMS": true,
  "ageCheck": true,
  "tags": [
    "text"
  ],
  "isWebinar": true
}

{
  "statusCode": "MTANoLinkedAccountError",
  "success": true,
  "error": "text",
  "message": "text",
  "data": {
    "id": 1,
    "created": "2025-04-24T05:49:47.682Z",
    "longUrl": "text",
    "shortUrl": "text",
    "finalUrl": "text",
    "trackingEnabled": true,
    "isMms": true,
    "clicks": 1,
    "tags": [
      {
        "id": 1,
        "tag": "text"
      }
    ]
  }
}

Templates API endpoints

View all templates

You can call GET /templates to see all the available templates on your account:

List Templates GET /templates

List Templates

get

Authorizations

Query parameters

pagenumberOptional

pageSizenumberOptional

sortBystringOptional

sortDirectionstring · enumOptionalAvailable options:

orderone of[] · min: 2 · max: 2Optional

The first item in the array must be the first item type and the second must be the second item type.

querystringOptional

Responses

application/json

all ofOptional

application/json

application/json

application/json

application/json

get

HTTPcURLJavaScriptPython

GET /v3/templates HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer apiKey
Accept: */*

{
  "statusCode": "MTANoLinkedAccountError",
  "success": true,
  "error": "text",
  "message": "text",
  "data": {
    "rows": [
      {
        "id": 1,
        "name": "text",
        "message": "text",
        "timestamp": "2025-04-24T05:49:47.682Z",
        "attachment": "text",
        "mms": true
      }
    ],
    "page": 1,
    "pageSize": 1,
    "total": 1
  }
}

View a specific template

To see the details on a specific template, you will need the {id} of the template. Then call GET /templates/{id} :

Get Template GET /templates/{id}

Get Template

get

Authorizations

Path parameters

idstringRequired

Query parameters

isMMSstringRequired

Responses

application/json

all ofOptional

application/json

application/json

application/json

application/json

get

HTTPcURLJavaScriptPython

GET /v3/templates/{id} HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer apiKey
Accept: */*

{
  "statusCode": "MTANoLinkedAccountError",
  "success": true,
  "error": "text",
  "message": "text",
  "data": {
    "id": 1,
    "name": "text",
    "message": "text",
    "timestamp": "2025-04-24T05:49:47.682Z",
    "attachment": "text",
    "mms": true
  }
}

Update a specific template

To make changes to a specific template, you will need the {id} of the template. Then call PATCH /templates/{id} with the body containing the new template data, message is required.

isMMS will default to false and a SMS template will be created unless an attachment is provided. If name is not provided, up to the first 32 characters of the message will be used as the name.

Example request:

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
}'

Update Template PATCH /templates/{id}

Update Template

patch

Authorizations

Path parameters

idstringRequired

Body

namestringOptional

messagestringOptional

attachmentstringOptional

isMMSbooleanOptional

updateAsMMSbooleanOptional

Responses

application/json

all ofOptional

application/json

application/json

application/json

application/json

patch

HTTPcURLJavaScriptPython

PATCH /v3/templates/{id} HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer apiKey
Content-Type: application/json
Accept: */*
Content-Length: 84

{
  "name": "text",
  "message": "text",
  "attachment": "text",
  "isMMS": true,
  "updateAsMMS": true
}

{
  "statusCode": "MTANoLinkedAccountError",
  "success": true,
  "error": "text",
  "message": "text",
  "data": {
    "id": 1,
    "name": "text",
    "message": "text",
    "timestamp": "2025-04-24T05:49:47.682Z",
    "attachment": "text",
    "mms": true
  }
}

Delete a Template

To remove a specific template, you will need the {id} of the template, then call DELETE /templates/{id}

Delete Template DELETE /templates/{id}

Delete Template

post

Authorizations

Path parameters

idstringRequired

Body

isMMSbooleanRequired

Responses

application/json

objectOptional

application/json

application/json

application/json

application/json

post

HTTPcURLJavaScriptPython

POST /v3/templates/{id} HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer apiKey
Content-Type: application/json
Accept: */*
Content-Length: 14

{
  "isMMS": true
}

{
  "statusCode": "MTANoLinkedAccountError",
  "success": true,
  "error": "text",
  "message": "text",
  "data": null
}

Create a new template

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

isMMS will default to false and a SMS template will be created unless an attachment is provided. If name is not provided, up to the first 32 characters of the message will be used as the name.

Example request:

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

Create Template POST /templates

Create Template

post

Required Fields: message

Defaults:
isMMS will default to false and a regular sms template will be created unless an attachment is provided. If name is not provided, up to the first 32 characters of the message will be used as the name.

undefined

Authorizations

Body

namestringOptional

messagestringRequired

attachmentstringOptional

isMMSbooleanOptional

Responses

application/json

all ofOptional

application/json

application/json

application/json

application/json

post

HTTPcURLJavaScriptPython

POST /v3/templates HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer apiKey
Content-Type: application/json
Accept: */*
Content-Length: 65

{
  "name": "text",
  "message": "text",
  "attachment": "text",
  "isMMS": true
}

{
  "statusCode": "MTANoLinkedAccountError",
  "success": true,
  "error": "text",
  "message": "text",
  "data": {
    "id": 1,
    "name": "text",
    "message": "text",
    "timestamp": "2025-04-24T05:49:47.682Z",
    "attachment": "text",
    "mms": true
  }
}

Template-Only Sending

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

List Controlled Templates GET /controlled-templates

List Controlled Templates

get

Authorizations

Responses

application/json

all ofOptional

application/json

application/json

application/json

application/json

get

HTTPcURLJavaScriptPython

GET /v3/controlled-templates HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer apiKey
Accept: */*

{
  "statusCode": "MTANoLinkedAccountError",
  "success": true,
  "error": "text",
  "message": "text",
  "data": {
    "rows": [
      {
        "id": 1,
        "accountId": 1,
        "name": "text",
        "message": "text",
        "requiresLink": true,
        "type": "dispensary",
        "isMMS": true,
        "url": "text",
        "createdAt": "2025-04-24T05:49:47.682Z",
        "updatedAt": "2025-04-24T05:49:47.682Z",
        "assignedChildAccounts": [
          {
            "id": 1,
            "accountName": "text"
          }
        ]
      }
    ],
    "page": 1,
    "pageSize": 1,
    "total": 1
  }
}

Get Controlled Template Endpoint GET /controlled-templates/{controlledTemplateId}

Get Controlled Template

get

Authorizations

Path parameters

controlledTemplateIdstringRequired

Responses

application/json

all ofOptional

application/json

application/json

application/json

application/json

get

HTTPcURLJavaScriptPython

GET /v3/controlled-templates/{controlledTemplateId} HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer apiKey
Accept: */*

{
  "statusCode": "MTANoLinkedAccountError",
  "success": true,
  "error": "text",
  "message": "text",
  "data": {
    "id": 1,
    "accountId": 1,
    "name": "text",
    "message": "text",
    "requiresLink": true,
    "type": "dispensary",
    "isMMS": true,
    "url": "text",
    "createdAt": "2025-04-24T05:49:47.682Z",
    "updatedAt": "2025-04-24T05:49:47.682Z",
    "assignedChildAccounts": [
      {
        "id": 1,
        "accountName": "text"
      }
    ]
  }
}

Template Examples

• 91 Sample Text Messages to Customers, Message Templates
• 43 Auto Reply Text Message Examples (+ 3 Tips)