Liquid Templates
Learn how to use content templates in your /createMessage API requests
Liquid Templates significantly broaden Pushwoosh personalization capabilities by implementing sophisticated logic in addition to regular Dynamic Content usage.
To ensure your customer communications are a direct hit, you should make them as relevant as possible. Modifying the content of the message according to users' identities, behaviors, and preferences is the most efficient way to increase relevance and get more impressive results of your marketing campaigns. For some cases, Dynamic Content personalizing the message with the user's Tag values is pretty fine. For others, its capabilities are not enough: let's say you'd like to send different content to users from different countries; that's where Liquid Templates come in handy. The Liquid logic gives you vast opportunities to make your customer communications perfectly personal and relevant.
Dynamic Content lets you fill in the message's content, title, subtitle, or image with Tag values associated with the user. Liquid Templates, in turn, allow implementing the logic to deal with these Tag values — the patterns for outputting the data depending on conditions you specify.
Content templates based on Liquid by Shopify use a combination of tags, objects, and filters to load dynamic content. Content templates allow to access certain variables from within a template and output their data without having to know anything about the data itself.
objects define the content that will be displayed to a user. objects should be enclosed in double curly braces: {{ }}For example, when personalizing a message, send
{{Name}} in its body to add the users' names to the message's content. The user's name (Name tag value) will replace the Liquid object in a message the user will see.Input
Output
Hi {{Name}}! We're glad you're back!
Hi Anna! We're glad you're back!
tags create the logic and control flow for templates. The curly brace percentage delimiters {% and %} and the text that they surround do not produce any visible output when the template is rendered. This lets you assign variables and create conditions or loops without showing any of the Liquid logic to a user.For example, using the
if tag, you can vary the message's language based on what language is set on user's device:Input
Output (fr)
Output (es)
{% if Language == 'fr' %}
Salut!
{% else %}
Hello!
{% endif %}
Salut!
Hello!
== | equals |
!= | does not equal |
> | greater than |
< | less than |
>= | greater than or equal to |
<= | less than or equal to |
or | logical or |
and | logical and |
contains | checks for the presence of a substring inside a string or array of strings |
In tags with more than one
and or or operator, operators are checked in order from right to left. You cannot change the order of operations using parentheses — parentheses are invalid characters in Liquid and will prevent your tags from working.filters modify the output of a Liquid object or variable. They are used within double curly braces {{ }} and variable assignment, and are separated by a pipe character |. Multiple filters can be used on one output, and are applied from left to right.Input
Output
{{ Name | capitalize | prepend: "Hello " }}
Hello Anna
Liquid Templates are available both for messages sent from Control Panel and API requests.
In Pushwoosh Control Panel, the Liquid Templates are applicable for all the content fields of any channel messsages:
To add a Liquid Template to your message content, just insert it into message's body.
You can use your tag values in templates by referring their name, for example:
{% if TagName == 'value' %} Content to send in this scenario {% else %} Content to send otherwise {% endif %}Template variables (Pushwoosh Tags) should not contain any spaces and have only alphanumeric values and underscores, e.g.,
my_tag or myTag instead of My Tag.For emails, insert the Liquid code into your Email Template HTML by adding the HTML block while building a template in editor or uploading an HTML template containing the Liquid logic.
Use the Liquid syntax in your
/createMessage requests to implement Liquid Templates. Templates are available for the "content" parameter of /createMessage request, as well as for any other parameter supporting Dynamic Content, in particular, platform-specific "title", "subtitle", and "image" params. By using content templates, you can either specify the data in your API requests (passing the "template_bindings" parameter) or get the data from Tag values stored on users' devices (by not using the "template_bindings" parameter). This way, you're able to build user-based push campaigns containing the extremely relevant content.
Please note, that unlike Dynamic Content, the variables in templates should be enclosed into double curly braces as follows:
{{myVariable}}.To define the template logic using the Tags with spaces in their names, use the following technique:
Example
{% capture my_tag %}{{My Tag}}{%endcapture%}
{% if my_tag == 'value' %}
Content to send in this case
{%else%}
Content to send otherwise
{%endif%}
Here you'll find several use cases when Liquid Templates come in handy.
Liquid Templates make it possible to definitely specify in what language should users receive your push messages. Look at the simple example of the API request and the message received depending on template bindings used in the request.
Liquid input
API request
Language is 'es'
Language is 'en'
{% if Language == 'es' %}
¡Hola!
{% else %}
Hello!
{% endif %}
Example
{
"request": {
"application": "XXXXX-XXXXX", // Pushwoosh app code
"auth": "yxoPUlw.....IyEX4H", // API access token from Pushwoosh Control Panel
"notifications" : [ // push message parameters
{
"content": "{% if language == 'es' %}¡Hola!{% else %}hello!{% endif %}",
"template_bindings": { // optional. When no template_bindings are passed in a request, Tag values from the device are used.
"language" : "es"
}
}
]
}
}
Encourage your customers to upgrade their subscription based on their current plan.
Liquid input
API request
Output
{% if Subscription == 'Basic' %}
Upgrade to Silver for getting more product features and 24/7 support.
{% elsif Subscription == 'Silver' %}
Upgrade to Gold for priority support and advanced features.
{% else %}
Please contact your manager to renew your subscription.
{% endif %}
{
"request": {
"application": "XXXXX-XXXXX", // Pushwoosh app code
"auth": "yxoPUlw.....IyEX4H", // API access token from Pushwoosh Control Panel
"notifications" : [ // push message parameters
{
"content": "{% if Subscription == 'Basic' %}Upgrade to Silver for getting more product features and 24/7 support.{% elsif Subscription == 'Silver' %}Upgrade to Gold for priority support and advanced features.{% else %}Please contact your manager to renew your subscription. {% endif %}",
"template_bindings": { // optional. When no template_bindings are passed in a request, Tag values from the device are used.
"language" : "es"
}
}
]
}
}
For users with Basic subscription plan: Upgrade to Silver for getting more product features and 24/7 support.
For users with Silver subscription plan: Upgrade to Gold for priority support and advanced features.
For users with plans other than Basic or Silver: Please contact your manager to renew your subscription.
Content templates are quite helpful to handle Tags of a List type.
One of the possible use cases is to deliver different content depending on the number of values the Tag contains. For example, you can provide different discounts to customers with different behaviors. Let's say the customer has some items in their WishList - encourage them to purchase with the most fitting discount based on how many products they're going to buy!
Liquid input
API request
WishList size >=3
WishList size = 2
{% if WishList.size >= 3 %}
Get 20% off your next purchase!
{% elsif WishList.size == 2 %}
Get a 10% discount on your next purchase!
{% else %}
Hey, take a look at new outwears!
{% endif %}
Example
{
"request": {
"application": "XXXXX-XXXXX", // Pushwoosh app code
"auth": "yxoPUlw.....IyEX4H", // API access token from Pushwoosh Control Panel
"notifications" : [ // push message parameters
{
"content": "{% if WishList.size >= 3 %}Get 20% off your next purchase!{% elsif WishList.size == 2 %}Get a 10% discount on your next purchase!{% else %}Hey, take a look at new outwears!{% endif %}",
"template_bindings": { // optional. When no template_bindings are passed in a request, Tag values from the device are used.
"WishList" : ["Skinny Low Ankle Jeans", "Linen Trenchcoat", "High Waisted Denim Skirt", "Strappy Tiered Maxi Dress"]
}
}
]
}
}
One more case you might need to cover is to deal with List Tags values and deliver the most relevant content based on what values the Tag contains.
Liquid input
API request
Variable contains data
Variable does not contain data
{% if WishList contains 'Skinny Low Ankle Jeans' %}
Get 20% off products in your wishlist!
{% else %}
Hey, take a look at the brand new Skinny Low Ankle Jeans!
{% endif %}
Example
{
"request": {
"application": "C90C0-0E786",
"auth": "yxoPUlw.....IyEX4H", // API access token from Pushwoosh Control Panel
"notifications" : [ // push message parameters
{
"content": "{% if WishList contains 'Skinny Low Ankle Jeans' %}Get 20% off your next purchase!{% else %}Hey, take a look at the brand new Skinny Low Ankle Jeans!{% endif %}",
"template_bindings": { // optional. When no template_bindings are passed in a request, Tag values from the device are used.
"WishList" : ["Skinny Low Ankle Jeans", "Linen Trenchcoat", "High Waisted Denim Skirt", "Strappy Tiered Maxi Dress"]
}
}
]
}
}
By using the content templates, you're able to adjust messages content according to users' behavior. For example, you can modify the message text to contain plural words in case the List Tag contains more than one value.
Liquid input
API request
Plural
Singular
Get 20% off item
{% if WishList.size > 1 %}
s in your WishList!
{% else %}
in your Wishlist!
{% endif %}
Example
{
"request": {
"application": "C90C0-0E786",
"auth": "yxoPUlw.....IyEX4H", // API access token from Pushwoosh Control Panel
"notifications" : [ // push message parameters
{
"content": "Get 20% off item{% if WishList.size > 1 %}s in your WishList!{% else %} in your Wishlist!{% endif %}",
"template_bindings": { // optional. When no template_bindings are passed in a request, Tag values from the device are used.
"WishList" : ["Skinny Low Ankle Jeans", "Linen Trenchcoat", "High Waisted Denim Skirt", "Strappy Tiered Maxi Dress"]
}
}
]
}
}
Template for timezones converts the date and time according to the timezone specified.
Liquid input
API request
Output
{{ MyDate | timezone: MyTimezone | date: \"%Y-%m-%d %H:%M\" }}
Example
{
"request" : {
"auth" : "3H9bk8w3.....Acge2RbupTB", // API access token from Pushwoosh Control Panel
"application" : "XXXXX-XXXXX", // Pushwoosh app code
"notifications" : [ // push message parameters
{
"content": "Current Date: {{ MyDate | timezone: MyTimezone | date: \"%Y-%m-%d %H:%M\" }}",
"template_bindings": { // optional. When no template_bindings are passed in a request, Tag values from the device are used.
"MyDate" : "2019-07-23 15:00",
"MyTimezone" : "Asia/Dubai"
}
}
]
}
}
Last modified 28d ago