Message Variants

Message variants let you send different versions of a message to different recipients, as part of the same message, broadcast, campaign, or service. Each variant has its own conditions and its own message content, and Telerivet automatically chooses which version to send to each recipient.

For example, you can use message variants to:

• Send quick reply buttons or a link button to recipients on WhatsApp or other chat apps, and plain text instructions (e.g. "Reply 1 for yes or 2 for no") to recipients on SMS.
• Send a message with an image or other media attachment when using a WhatsApp or MMS route, while using a plain text message for SMS routes.
• Send the message in each contact's preferred language, based on a contact field.
• Send a different message to contacts in a particular group.
• Run an A/B test by sending different versions of a message to random samples of recipients, and compare the delivery, read, response and click rates of each version.

Where You Can Use Message Variants

Message variants are available for text messages (not voice calls) in the following places:

• The New Message dialog, when sending or scheduling a message
• Broadcast campaigns and relative campaigns (for text messages)
• Scheduled messages
• Actions that send or reply with a text message in custom actions services
• Poll questions, and replies sent by polls
• Message templates
• The REST API, using the variants parameter when sending messages, broadcasts, or scheduled messages

Adding a Variant

In the message editor, click the variants icon in the toolbar below the message ("Add variant for specific routes or contacts"), then choose the kind of condition for the variant: Random sample, Route, Contact field, Contact group, or Other variable.

The variant appears below your original message, which is now labeled "Default message". The new variant starts with a copy of the default message, which you can edit — including its text, media attachments, route-specific parameters (such as quick replies or link buttons), and link shortening/click tracking settings.

Next to "Send this version instead of the default when", enter the condition for the variant. To add more conditions, click the + icon after the last condition. When a variant has multiple conditions, choose whether the variant is used when "all conditions match" or when "any condition matches".

To add more variants, click "+ Add another variant". Each message can have up to 10 variants, and each variant can have up to 5 conditions (not counting a random sample). To remove a variant, click the delete icon at the top right of the variant.

Types of Conditions

• Random sample — the variant is sent to approximately a certain percentage of recipients, selected at random. See A/B Testing with Random Samples below.
• Route — depends on the basic route that sends the message: whether the route supports (or does not support) quick replies, a link button, or media attachments; the route's type (e.g. WhatsApp); or a particular route.
• Contact field — compares a contact field, such as the contact's name or a custom field like Language, with a value.
• Contact group — whether a particular contact group includes (or does not include) the recipient.
• Other variable — compares any other variable that is available when sending a message, such as the recipient's phone number. Variables may also include filters, e.g. [[contact.vars.language|default:"en"]].

Additional comparison types (e.g. "contains" or "is one of") are available by choosing "More conditions…" in the comparison dropdown.

How Telerivet Chooses a Variant

When a message is sent to each recipient, Telerivet checks each variant in order, and sends the first variant whose conditions match. If no variant's conditions match, the default message is sent.

Each variant is a complete replacement for the default message. Its text, media attachments, route-specific parameters, and link settings are not combined with the default message.

Since the first matching variant is used, more specific variants should be listed before more general ones. For example, a variant for "Language is fr and Random sample (~50%)" should be listed before a variant for "Language is fr", since otherwise the more specific variant would never be used. If a variant could never be used because of an earlier variant, Telerivet will show an error when you save the message. To change the order of the variants, drag the handle to the left of the variant's title.

Route conditions are checked using the basic route that actually sends each message. If you send messages via a custom route that contains multiple basic routes, the variant may depend on which basic route sends each message. If a message is resent or fails over to a different basic route, Telerivet checks the conditions again and may send a different variant.

Using Variables in Conditions

Conditions can use the same variables that are available in the content of outgoing messages, including contact variables such as [[contact.name]] and [[contact.vars.language]], and variables of the route that sends the message:

• [[phone.type]] — the type of the route, e.g. whatsapp
• [[phone.supports_quick_replies]], [[phone.supports_link_button]], [[phone.supports_native_attachments]] — 1 if the route supports quick replies, a link button, or sending media attachments directly (rather than as links), otherwise 0
• [[phone.id]] and custom route variables such as [[phone.vars.region]]

In services and polls, variant conditions can't use variables that are only available within the service, such as the content of the incoming message ([[content]]) or the conversation state ([[state.id]]). To choose a variant based on these values, first store the value in a contact field (e.g. with the "Set contact variable" action), and then use the contact field in the variant's condition.

A/B Testing (Split Testing) with Random Samples

To compare how different versions of a message perform, add a variant with a "Random sample" condition, and enter the percentage of recipients who should receive the variant. For example, to compare two versions of a message, add one variant with a random sample of 50%, so that about half of the recipients receive the variant and the other half receive the default message. To compare three versions, add two variants, each with a random sample of 33%.

Recipients are selected randomly, so the actual number of recipients who receive each variant may differ slightly from the percentage, especially when sending to a small number of recipients. Each contact is always in the same random sample for all messages in the same broadcast or campaign, including when a message is resent.

A random sample can be combined with other conditions, for example to run separate A/B tests for recipients on WhatsApp and recipients on SMS, or for contacts in different languages. In this case, the random sample is a percentage of the recipients who match the variant's other conditions, and all of the variant's conditions must match. The random samples of variants with the same other conditions can add up to at most 100%.

If you don't want Telerivet to assign recipients to random samples automatically, you can choose which contacts receive each version yourself. For example, when importing contacts, you can include a column indicating which version each contact should receive and import it as a custom contact field (e.g. "Test Group"), or add the contacts for each version to a separate contact group. Then use a Contact field or Contact group condition for each variant, instead of a random sample. The Variants table shows the results for each variant in the same way.

Viewing the Results of Each Variant

When you view a broadcast or campaign that has message variants, the Variants table shows statistics for the default message and each variant, including the number of messages, the number of messages with each status (e.g. Delivered or Read), the number of replies and link clicks, and the cost.

When there is enough data, a star (★) appears next to the delivery rate, read rate, response rate, or click rate of a variant that has at least a 95% chance of having the highest rate. Hover over a rate to see the probability that each version has the highest rate, and how its rate compares with the default message.

Note that variants that are selected by conditions (other than random samples) may be sent to different kinds of recipients. For example, recipients on WhatsApp may be more likely to reply than recipients on SMS, regardless of the message content. To compare message content fairly, use random samples.

On the Message Detail page for each message, the Variant field shows which variant was sent (e.g. "Variant 2: Language is es"), or "Default message". The exported CSV file for messages also includes a Variant column.

Message Templates with Variants

When you save a message as a message template, its variants are also saved with the template. When you use a template that has variants, the variants are restored along with the default message.

When you choose a template for the default message that doesn't have any variants, only the default message is replaced, and your existing variants are kept. When choosing a template for a variant, templates that have variants are not shown.