Message variables

A variable is a placeholder in the text of a message. Each recipient gets their own value in its place — a name, a company name, an order number. That way you send one text to thousands of people and each of them reads a message written for them. Variables are written the same way in a campaign and in the API.

How to write a variable

A variable is a name in angle brackets, for example <first_name>. When the message is sent, it is replaced with the value you have for that recipient:

• The name has to match exactly. Letter case and spaces matter — neither <First_Name> nor < first_name > is replaced with the first_name value.
• An empty value is the same as none. Empty text or nothing but spaces counts as a missing value — what happens then is described in When the value is missing.

When the value is missing

When you have no value for a recipient, the variable stays in the message literally — the recipient gets Hi <first_name>, …. You prevent that with a default value written after a colon:

A recipient you do have a value for gets their own value in all three cases.

Length limit

After an equals sign you write the maximum number of characters the value may have: <company_name=8>. It comes in handy for long values such as a company name or an address, which would otherwise stretch the message into another SMS part. The letter after the number decides what happens to a longer value:

A value that fits within the limit is inserted in full.

Variables in a campaign

A campaign takes the values from the contacts you add to it — from the address book, from a file import and from numbers entered by hand.

1. Add the recipients first. The variable menu only shows fields that at least one recipient of the campaign has filled in. Without recipients it is empty.
2. In the text editor, click the Add variable icon, or just type @. Typing a name narrows the menu down.
3. Pick the variable. For each one you can see what percentage of recipients have data for it.

The variable shows up in the text as a tag with the field name, and its colour tells you how you are doing with the data:

• no highlight — every recipient has the data, or a default value is set,
• warning — 30 to 99 % of recipients have the data,
• error — fewer than 30 % of recipients have the data, or no such field exists.

Click the tag to edit the variable: add a fallback text, let it be left out, or limit the number of characters (1 to 50). The editor saves it in the same notation described in When the value is missing and Length limit.

Which fields you can use

When you import from a file, you map each column to one of these fields. A column that none of them fits — an order number, a discount amount — goes to a custom field, and in the text you then use, for example, <custom_field_0>.

Channels, length and preview

• Channels. Variables work in the message text of SMS, Viber and RCS, and for RCS in the title too.
• Length and price. The character counter in the editor counts with the values of the contact selected in the preview. Each recipient may have values of a different length, though — so the number of SMS parts and the price are calculated for each recipient separately, after the values are filled in.
• Unicode. Diacritics from a filled-in value switch the SMS to Unicode only when you have it enabled in the text settings.
• Preview. Both the message preview and Send test message fill in the values of the contact selected in the preview — so you see how the text turns out before it is sent.

Variables in the API

In the API you send the values right in the request, in the variables parameter: an object whose key is the variable name and whose value is what should be filled in. The text uses the same notation, including default values and length limits.

The recipient gets Hi Peter, order 12345 is on its way. You can name a variable however you like — <order> in the example is not a contact field, just a key from variables.

Where the variables go

What values to send

• Text or a number. Numbers are filled in as they are (12 → 12).
• null, false and empty text count as a missing value — the default value applies, otherwise the variable stays in the text literally.
• An array or an object as a value is not accepted by the Advanced API, which returns the error invalid_input_parameters.
• Extra keys that are not in the text are ignored.
• Vocative case. From first_name and last_name the Advanced API works out first_name_vokativ and last_name_vokativ by itself — it overwrites your own values of these two keys. The Integration API does not work out the vocative. How it works is described in Czech vocative.

Channels and length

The number of SMS parts and the price are both calculated from the text after the values are filled in. Diacritics from a filled-in value switch the SMS to Unicode only with "unicode": true. Viber, RCS and WhatsApp text that grows beyond the channel limit after the values are filled in (Viber 1,000 characters, RCS and WhatsApp 5,000) is cut short.