Merge Tags

Merge tags are placeholders you embed in a message body that the platform substitutes with per-recipient or per-account values at send time. The same syntax works on every send endpoint.

# Body sent
"Hi {{contact_first_name}}, your {{contact_custom_field_1}} tier rewards are ready!"

# Body delivered to a recipient whose contact has firstName=Alice + custom field 1=Gold
"Hi Alice, your Gold tier rewards are ready!"

How resolution works

For every recipient, the platform:

1. Scans the body for {{...}} placeholders.
2. Resolves each placeholder against the recipient's contact profile (looked up by phone number against your account's contact book) or your account's configuration.
3. Substitutes the resolved values into the body.
4. Sends the resulting per-recipient message via the carrier.

One API call → personalized messages for every recipient. The platform does the contact lookup automatically — you don't need to fetch profile data yourself and string-template the body.

Missing data resolves to an empty string

Worked example — same body sent to three recipients:

Body: "Hi {{contact_first_name}}, your {{contact_custom_field_1}} tier reward is ready."

Plan your wording so the message reads naturally when a variable is blank. When personalization isn't critical, prefer non-templated copy ("Welcome back!") over a templated greeting that might render "Hi , welcome back!".

Where merge tags work

The same resolver and variables apply to all three send endpoints:

Same variables, same empty-string behavior on missing data, same resolver on all three.

Available variables

Contact-scoped variables

Resolved from the recipient's contact record (looked up by phone number):

Date helpers

Offer expires {{dateOffset "7d"}}.  →  Offer expires 05/24/2026.

Tracking links

Body sent
"Tap to redeem: {{trackingLink "fct.la/promo"}}"

Body delivered (recipient Alice)
"Tap to redeem: fct.la/abc/xy7z"

Tracking links resolve before merge-tag variables, so you can pair them in a single body without ordering issues:

"Hi {{contact_first_name}}, your {{contact_custom_field_1}} reward awaits: {{trackingLink "fct.la/rewards"}}"

For multi-recipient sends the annotation is computed per-recipient, so each contact's click ties back to their own contact record — no extra integration on your side.

Custom field variables

Custom-field variables follow the pattern {{contact_custom_field_N}} where N is the 1-based position of the field in your account's schema (1 = your first custom field, up to 7).

If you set up your custom fields ahead of time and know their order, hard-code the merge tags directly in your message bodies — no extra API call needed. For dynamic integrations that want to discover available fields at runtime (e.g. a "Send a Campaign" UI in your own dashboard), fetch the schema once and read the key field of each entry:

curl -X GET https://platform.textingline.com/api/v1/contacts/custom-fields/schema \
  -u "your_key_id:your_key_secret"

// Node 18+ (global fetch)
const KEY_ID = process.env.TEXTINGLINE_KEY_ID;
const KEY_SECRET = process.env.TEXTINGLINE_KEY_SECRET;
const auth = 'Basic ' + Buffer.from(`${KEY_ID}:${KEY_SECRET}`).toString('base64');

const res = await fetch(
  'https://platform.textingline.com/api/v1/contacts/custom-fields/schema',
  { headers: { Authorization: auth } },
);
const schema = await res.json();
// schema.fields is an array of { label, key, type, options? }
// Build a label → merge-tag-name map for your authoring UI:
const tagByLabel = Object.fromEntries(
  schema.fields.map((f) => [f.label, `{{${f.key}}}`]),
);
console.log(tagByLabel);
// → { "Favorite Color": "{{contact_custom_field_1}}", "Birthday": "{{contact_custom_field_2}}" }

import os
import requests
from requests.auth import HTTPBasicAuth

AUTH = HTTPBasicAuth(
    os.environ['TEXTINGLINE_KEY_ID'],
    os.environ['TEXTINGLINE_KEY_SECRET'],
)

resp = requests.get(
    'https://platform.textingline.com/api/v1/contacts/custom-fields/schema',
    auth=AUTH,
)
resp.raise_for_status()
schema = resp.json()
# schema['fields'] is a list of { label, key, type, options? }
tag_by_label = {f['label']: f"{{{{{f['key']}}}}}" for f in schema['fields']}
print(tag_by_label)
# → {'Favorite Color': '{{contact_custom_field_1}}', 'Birthday': '{{contact_custom_field_2}}'}

{
  "fields": [
    { "label": "Favorite Color", "key": "contact_custom_field_1", "type": "SINGLE_SELECT", "options": ["Red", "Green", "Blue"] },
    { "label": "Birthday",       "key": "contact_custom_field_2", "type": "DATE" },
    { "label": "Points",         "key": "contact_custom_field_3", "type": "NUMBER" }
  ]
}

Each entry has a label (the operator-chosen display name, used as the JSON key when reading/writing customFields on a contact), a key (the merge-tag variable name — embed inside {{...}} in message bodies), and a type (one of TEXT, NUMBER, BOOLEAN, DATE, SINGLE_SELECT, MULTI_SELECT). SINGLE_SELECT / MULTI_SELECT entries also include options listing the allowed values.

The key field is stable across label renames. If you rename "Favorite Color" → "Color" in the dashboard, your existing templates referencing {{contact_custom_field_1}} keep working. (Your integration's customFields JSON paths — e.g. "customFields": { "Favorite Color": ... } — would need updating, but the merge-tag side is unaffected.) See Custom Fields.

Unknown placeholders pass through

The resolver only touches known variables. If a body contains a {{...}} placeholder that isn't a recognized merge tag (e.g. {{order_id}}), the placeholder is left as-is in the delivered text — it isn't replaced and it isn't an error. This protects unrelated {{...}} substrings embedded in URLs or JSON payloads from being mangled.

If you're authoring templates programmatically and want to catch typos, validate against the variable list on this page before sending.

Encoding & message length

Substituted values count toward the SMS segment budget. Two things to watch:

• GSM-7 vs UCS-2 encoding. Standard SMS uses 7-bit GSM-7 encoding (160 chars per segment). The moment a body contains any character outside the GSM-7 alphabet — emoji, curly quotes (" / "), em dashes (—), accented letters (é, ñ), most non-Latin scripts — the entire SMS switches to UCS-2 encoding (70 chars per segment). A firstName of Renée will quietly halve your segment capacity for that recipient. If you need to support arbitrary names, plan for UCS-2 budgets.
• Phone-number formatting. {{contact_phone_number}} resolves to the international form with spaces (+1 213 373 4253 — 15 chars), not E.164 (+12133734253 — 12 chars). Adds 3 characters per US recipient versus E.164.

There's no compile-time check for either — both happen at carrier-encoding time, after substitution. Test bodies that approach the 160-char limit with real recipient data (including a name with accented characters and an emoji) to confirm the segment count.

Common pitfalls

A short list of the issues that come up most often, in roughly the order we see them in support:

1. Typos resolve to empty strings, not errors. {{contact_first_naem}} is an "unknown placeholder" and survives literally; {{first_name}} (missing the contact_ prefix) is also unknown. The platform doesn't validate template authoring at submit time. Cross-check every variable name against the Available variables table above before going to production. For dynamic templates, also call the schema endpoint and validate against the returned key values.
2. Recipient must be a saved contact for personalization to work. A phone number that isn't in your contact book gets every merge tag in the body resolved to an empty string. Seed your contact book first — see Upsert a contact from a CRM.
3. Test with one recipient before blasting thousands. Send the same templated body to a single test contact (with realistic field values), inspect the delivered SMS on a real phone, then run the full broadcast/batch. Catches encoding surprises, accidental empty fields, missing tracking-link registrations, and unnatural wording with blanks.
4. mediaUrl is not templated. Merge tags are only substituted in body — putting {{contact_first_name}} in mediaUrl will send a literal request to that URL with the braces intact (and likely 404). For per-recipient media, use the batch endpoint and compute the mediaUrl yourself for each recipient.
5. Tracking-link arg must be the bare domain/path. No scheme, no query params, no trailing slash — see the Tracking links callout. Mistakes here silently break click-through analytics without breaking the send.
6. Merge-tag substitutions count toward segment length. See Encoding & message length above.

Related

• Send a personalized broadcast with merge tags — full broadcast workflow (curl, JavaScript, Python).
• Custom Fields — manage the schema that powers {{contact_custom_field_N}}.
• Upsert a contact from a CRM — seed your contact book before sending.