MyComm docs
Menu

Data

Templates

Reusable message text with variables, how a variable gets its value, and how to preview before you send.

A template is saved message text with variables. Send it with template_id and variables instead of writing the text each time, and campaigns and automation replies use the same templates.

Write a template#

curl -sS -X POST "$MYCOMM_URL/v1/templates" \
  -H "Authorization: Bearer $MYCOMM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order ready",
    "body": "Hi {{ first_name | \"there\" }}, order #{{ order }} is ready for pickup."
  }'
  • {{ name }} inserts a value. {{ name | "fallback" }} uses the fallback when there is no value.
  • A syntax error answers 422 TEMPLATE_INVALID with details.position.
  • Names are unique among templates that are not archived, ignoring case (409 NAME_TAKEN).
  • A body that links through a public URL shortener is refused (LINK_PUBLIC_SHORTENER), and so is one estimated at more than 10 SMS parts (BODY_TOO_LONG).
  • Variables that are not a contact field or custom field are allowed, but you must supply them when you send; they are listed in the warnings of the answer.

Where a variable gets its value#

For one recipient, a variable takes the first of these that exists:

  1. the variables you pass with the send,
  2. the fields of the contact (first_name, last_name, email, ... and custom fields),
  3. the account's fields,
  4. the fallback written in the template.

A variable with no value and no fallback renders empty and is reported in missing_variables when you render. Values are plain text: they are never read as template syntax, and values over 500 characters are cut to 500.

Preview before you send#

Call Use it to
POST /v1/templates/preview Check unsaved text while someone is typing it
POST /v1/templates/{id}/render See a saved template as one recipient would get it (contact_id and variables optional; contacts:read is needed with contact_id)

Both return the rendered text with its segments and encoding, the missing_variables, and non_gsm_characters, the characters that force UCS-2 and shorten every segment. Nothing is written or sent.

Send with a template#

{"to": "+923001234567", "template_id": "0198ec30-4d12-7b6a-8f21-9a3c5e7d1b08", "variables": {"order": "1094"}, "category": "transactional"}

A message keeps the text it was rendered with, so editing a template later does not change messages already accepted. Archived templates cannot be sent (TEMPLATE_ARCHIVED); POST /v1/templates/{id}/restore brings one back.