Table of Contents

• Table of Contents
• What is Liquid?
• Liquid templates 
• What if I want to write my own Liquid?

What is Liquid?

Have you ever found yourself working with incomplete data or wanting to personalize your message copy for each of your contacts? Then the Liquid feature is for you! Liquid is a template language that not only allows you to add variables into your initial messages and canned responses, but also allows you to modify those variables directly from Scale to Win Text. 

For example, if you don’t know the first name of everyone on your contact list, you can use Liquid to set up a fallback word, such as “friend” or “team” (or any other word that works for your script), for those folks! With Liquid, you can also use variables to change the copy that each of your recipients sees, all from a single campaign.

The Message Preview section in Scale to Win Text simplifies using Liquid by allowing you to see exactly what your message will look like to different contacts! You can double check that the fallback you selected (such as displaying “Friend” or “there” if the first name column is blank for a contact) or the minimum you set for a donation_ask variable show up correctly. 

The message preview section will also let you know if the Liquid you’re using is creating an error, which prevents the script from rendering.

Note that if your entire campaign is experiencing rendering issues (i.e. if there’s an error in your Liquid), it will automatically pause, and you'll be notified on the Campaign Results page. If only certain contacts encounter problems due to mismatching data, you'll find details under the Initial Status section on the campaign results page. They’ll be marked as “Script Rendering Failed.”

Liquid templates 

We’ve written out some helpful templates for common situations where you might use Liquid! You can copy and paste these templates into your scripts, and replace the yellow highlighted sections with your own choices for fallbacks/minimum ask values/etc.

It's essential to consider data formatting when using Liquid templates. If a template relies on specific formatting, like numbers or text, and the data doesn't match that formatting, it might fail to render correctly. For example, attempting to compare a first name to a number (if first_name > 5) would lead to an error.

Setting a fallback for the first name variable

• If the first name variable is blank, display a fallback

• {{first_name | default: "FALLBACK"}}

Max/Min donation asks: 

If you’re including a number variable in your script, you can use these templates to modify that variable directly from STWT. For example, you may want to include the amount of the last donation each contact made, or a specific donation ask amount that’s based on previous donations made by each contact. In these examples, we’re using the variable name donation_ask, but you can always swap in your specific variable name – such as ask or hpc – to use these templates for other number variables!

• If the amount variable is blank or falls below a certain threshold, display a fallback value

• {{donation_ask | at_least: Min}}

Image description: For contacts with a donation_ask value below the minimum, this template will display the minimum value

Image description: For contacts without a donation_ask value, this template will also display the minimum (in this case, 20)!

• If the amount variable is above a certain threshold, display a fallback value (note that if someone has no amount listed – a blank for this variable – using this template will display a 0 for them)

• {{donation_ask | at_most: Max}}

Image description: For contacts with a donation_ask value above the maximum, this template will display the maximum.

Image description: For contacts without a donation_ask value, this template will display a 0.

• If the amount variable is blank, falls below a certain threshold, or is above a certain threshold, display a fallback value (note that this will display the min value for anyone with a blank for this variable)

• {{donation_ask | at_least: Min | at_most: Max}}

Image description: For contacts with a donation_ask below the minimum, this template will display the minimum.

Image description: For contacts without a donation_ask value, this template will display the minimum.

Image description: For contacts with a donation_ask value above the maximum, this template will display the maximum.

Replace 0 or blank amounts only

• If the amount variable is blank, display a fallback value (but do not set a minimum value for anyone with an amount variable value)

• {{donation_ask | default: fallback value}}

Image description: For contacts who do not have a donation_ask value, this template will display the default (fallback) value.

• If the amount variable is 0 or blank, display a fallback value (but do not set a minimum value for anyone with a non-zero amount variable value)

• {% if donation_ask == 0%}fallback value{%else%}{{donation_ask | default: fallback value}}{%endif%}

Image description: For contacts with a donation_ask value of 0 (or without a donation_ask value), this template will display the fallback amount (in this case, 10).

Image description: For contacts who have a non-zero donation_ask value, whether it is less than or greater than the fallback amount, this template will display their actual donation_ask.

Rounding a donation ask

• If you want to round your donation ask to the nearest whole number

• {{donation_ask | round}}

Image description: For contacts who have a donation_ask that isn't a whole number, this template will display the donation_ask rounded to the nearest whole number.

• If you want to round your donation ask up

• {{donation_ask | ceil}}

Image description: This template will round up any donation_ask that isn't a whole number.

• If you want to round your donation ask down

• {{donation_ask | floor}}

Image description: This template will round down any donation_ask that isn't a whole number.

*Please note that these templates rely on the amount variable being a number! If you include a dollar sign ($) in the data for the amount variable, this will change the format of the data to text, and using these templates on it will cause an error. Instead of putting the dollar sign into the data, simply include it in the text of your copy!

What if I want to write my own Liquid?

Liquid uses variables, filters and tags! 

Variables are just what they sound like! Any column you include in your CSV of contacts is a variable that you can use in your script. To display a variable, enclose its name in double curly brackets. For example, if you write out {{first_name}} in your script, the recipient’s first name would be displayed in the copy (or, if the recipient didn’t have a first name in your CSV, they would just see a blank).

Filters allow you to modify how a variable is displayed to a recipient. To use a filter, include it within the double curly brackets enclosing the variable you want to display – make sure you separate it from the variable using a | (called a pipe character)! You can use multiple filters on a single variable, again separating them from each other with a pipe character. If you use multiple filters at a time, they will be carried out from left to right.

You can see a full list of the filters available in Scale to Win Text, along with examples of how to use them, here!

You can write out {{first_name | default: 'friend'}} to either 1) display a first name for people who have one, or 2) display the word ‘friend’ for people who have a blank/no first name. You can also use filters to modify variables like an ‘ask’ value! For example, if you included {{donation_ask | at_least: 10 | round}} in your script, it would display a recipient’s ‘ask’ value, rounded to the nearest whole number, with a minimum ask value of 10. So if there was someone in your list with no ‘donation_ask’ value, or with a ‘donation_ask’ value below 10, they would see 10 in their text!

Some filters accept parameters, while others do not. The default and at_least filters do accept parameters, while the round filter does not.

Note that data formatting is very important in Liquid! Some variables will be string or text variables, while others will be numeric. If you are inputting a text parameter for a variable, you’ll want to enclose the parameter in either single or double straight quotation marks (for example, default: 'friend' or default: "friend"). If your fallback is a word that includes an apostrophe in it, such as “y’all”, enclose it in double quotation marks to ensure Liquid doesn’t read your apostrophe as a closing quotation mark and throw an error! The default filter can also be applied to numeric variables, and can also accept numeric parameters – for example, default: 10 can be applied to numeric variables.

Image description: Because first_name is a text variable, trying to apply a filter with a numeric parameter is causing an error.

Please be aware that Liquid accepts straight (' or ") quotation marks only – so if you copy and paste your Liquid formatting into STWT from somewhere else and get an error, it may be that you pasted in curly (‘ or “) quotation marks! Try deleting and retyping the quotations in STWT itself to correct for this.

If you’re inputting a numeric parameter for a numeric variable, you don’t need to use quotation marks (for example, at_least: 10), though doing so will not produce an error. As a reminder, if your Liquid is leading to a rendering error, you’ll be able to see that in the message preview section.

Image description: This example is missing quotation marks around the parameter (the text fallback of "friend") for the default filter, which is causing an error.

Tags are the conditional language that dictates the logic used in your script template. Let’s say you wanted to text a list of both donors and non-donors – you could use tags to have your script read “Thank you so much for your generous donations” for donors, and “Thank you so much for your support” for non-donors. 

Tags are enclosed in single curly brackets and percent signs, and typically use if/else language. You probably won’t use tags as often as you’ll use filters, but they can come in very handy for personalizing your scripts in more complicated ways!

For example, if you wanted people with a first name to see the sentence “first_name, thank you for your support” and people without a first name to see “Thank you for your support”, you could write out…

{% if first_name %}{{first_name}}, thank you for your support.{%else%}Thank you for your support.{%endif%}

The first part of this Liquid – {% if first_name %} – checks to see if the recipient has a first name value. If they do, the script will display the sentence that uses the first name variable. The {%else%} portion precedes the sentence that should be displayed if the recipient does not have a first name value. And finally, the {%endif%} portion ends this conditional language! 

Note that if you’ve added a fallback for first names directly into your CSV, people with the fallback will see the sentence that includes the first name variable For example, if your CSV includes people who have the fallback “Friend” as their first name, they will see the sentence “Friend, thank you for your support”. Only people who have no data for the first name variable (so a blank cell in the CSV) would see the sentence “Thank you for your support”.