TABLE OF CONTENTS |
What Is Liquid?
Have you ever worked with incomplete data or wanted to personalize your message copy for each of your contacts? Then the Liquid feature is for you! Liquid is a template language that lets you:
Insert variables into your initial messages and response scripts.
Define and modify those variables right within Scale to Win Text.
For example, if some contacts don’t have a first name on your list, you can use Liquid to insert a fallback word, such as “friend,” or “team,” or any other word that works for your script so every message still feels personal.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.
Message Preview
Scale to Win Text’s Message Preview simplifies using Liquid by showing you exactly how your messages will render for different contacts.
Message Preview will even flag any Liquid errors before you send.
Any Liquid error that affects your entire script will automatically pause the campaign and trigger an alert 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, each 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.
Note: Always check your data format before using a template. If you compare a text field to a number (for example, if first_name > 5). Liquid will throw an error and the script won’t render correctly.
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
When you include a number variable in your script, like donation_ask,you can use these templates to modify that variable directly from Scale to Win Text. 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}}
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}}
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}}
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}}
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%}
Rounding a donation ask
If you want to round your donation ask to the nearest whole number
{{donation_ask | round}}
If you want to round your donation ask up
{{donation_ask | ceil}}
If you want to round your donation ask down
{{donation_ask | floor}}
Please note: these templates rely on the amount variable being a number! If you include a dollar sign ($) in your amount variable data, Liquid will treat it as text, causing these templates to fail.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: 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.
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.
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!
Keep in mind that if you’ve populated the first name field in your CSV with a fallback, (for example, “Friend”), those contacts will see “Friend, thank you for your support.” Only contacts who have no data for the first name variable will see the message without a name, “Thank you for your support).
Liquid Template Generator
We also offer a Liquid Template generator to help you quickly draft scripts that include fallback first names and donation ask conditions. Here’s how to use it:
Make a copy of this sheet.
Add your script to cell B10.
Important: The sheet automatically looks for and replaces ‘first_name’ and/or ‘donation_ask’ placeholders.
Example: “Hi first_name, this is Grace with Scale to Win. Can you chip in donation_ask?”
Choose whether to use a fallback for first names.
If the ‘first_name’ cell is blank in your contact list, a fallback word will be used in the script. For example, if ‘first_name’ is blank, return ‘Friend’.
Check the box in C2, and add your preferred fallback name in F2.
Set donation ask conditions.
You can define a minimum, maximum, or fallback amount for ‘donation_ask’
Check the box in C3, then enter your values in F3-F5.
If you want to round your ‘donation_ask’ to the nearest whole number, mark the checkbox in C4.
Click “Generate” and copy and paste the result into your initial script editor.