Template Engine

Learn how to use content templates in your /createMessage API requests

Overview

Template Engine significantly broadens the Dynamic Content usage by implementing the sophisticated logic in addition to regular Dynamic Content capabilities.

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’ identity, behaviors, and preferences is the most efficient way to increase relevance and get more impressive results of your push campaigns. For some cases, Dynamic Content modifying the message with the user’s Tag values is pretty fine. For others, its capabilities are not enough. That’s why the Template Engine exists to make your marketing automation incredibly powerful and scalable.

Let’s say you’re going to remind customers of the shopping cart they abandon. How do you choose between plural ‘items’ and singular ‘item’ when writing the content of the message while you don’t know how many items exactly do your customers add to their carts? The Template Engine gives a simple but elegant solution: create the template based on ‘if’ logic operation to choose the correct word form depending on the number of items added to the user’s cart!

Dynamic Content lets you fill in the message’s content, title, subtitle, or image with Tag values associated with the user. Template Engine, in turn, allows implementing the logic to deal with these Tag values — the patterns for outputting the data depending on conditions you specify.

Implementation

Template Engine based on Liquid by Shopify uses 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. 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 simple-to-use user-based push campaigns containing the extremely relevant content.

Use the Liquid syntax in your /createMessage requests to implement the Template Engine. Templates are available for the 'content' parameter of /createMessage request, as well as for any other parameter supporting Dynamic Content, in particular, app-specific 'title', 'subtitle', and 'image' params.

Please note, that unlike Dynamic content, the variables in templates should be enclosed into double curly braces as follows: {{myVariable}}.

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.

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%}

To learn more about the template engine syntax, please refer to Liquid documentation.

Use cases

Here you'll find several use cases when the Template Engine comes in handy.

Multi-language push

Template Engine makes 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.

Request
Language is 'es'
Language is 'en'
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 %}",
"use_template" : true, // enables templating if set to 'true'
"template_bindings": { // optional. When no template_bindings are passed in a request, Tag values from the device are used.
"language" : "es"
}
}
]
}
}

Timezone

Template for timezones converts the date and time according to the timezone specified.

Request
Output
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\" }}",
"use_template" : true, // enables templating if set to 'true'
"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"
}
}
]
}
}

List Tags

Content templates are quite helpful to handle Tags of a List type.

Variable size

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!

Request
WishList size >=3
WishList size = 2
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 %}",
"use_template" : true, // enables templating if set to 'true'
"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"]
}
}
]
}
}

Variable contains

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.

Request
Variable contains data
Variable does not contain data
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 %}",
"use_template" : true, // enables templating if set to 'true'
"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"]
}
}
]
}
}

Plurals

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.

Request
Plural
Singular
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 %}",
"use_template" : true, // enables templating if set to 'true'
"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"]
}
}
]
}
}