Guides
Log InSign Up

Using Liquid Syntax

How to apply personalization to message content

Suggest Edits

To personalize the content of your messages, you can use Liquid Syntax. Liquid uses a combination of tags, filters, and conditional statements to ensure the right content is displayed at the right time.

You can personalize all messages, including email, push, sms, in-app, and live activities. Liquid Syntax is a templating language that OneSignal supports for messaging content. With Liquid Syntax, you can substitute names {{ name }} or apply more complex personalizations by adding logic {% if true %}.

To see more examples of liquid syntax, view the source documentation maintained by Shopify.

Fields that support Liquid syntax

Substitution is also available with the "Test & Preview" button within the dashboard.

Email

  • Subject, Reply-to, and Pre-header
  • Message Body
  • Image substitution is available within HTML Block or HTML Editor. Example: <img src="{{image_url}}"/>
  • Substitution can be tested with the "Test & Preview" button.

Push

  • Subject Line
  • Message Body
  • Image URL
  • Launch URL. Example: https://example.com/{{last_category_viewed}}
  • Substitution can be tested with the "Test & Preview" button.

SMS

  • Message Body
  • Substitution can be tested with the "Test & Preview" button.

In-App Messages

Only Tag substitution is supported at this time. Does not accept Property substitution.

  • Text Blocks
  • Button Blocks
  • Image Blocks
  • Substitution can be tested with the "Test & Preview" button.

Live Activities

  • Within the event_updates, contents and headings properties.

Syntax

There are two ways to use Liquid syntax in your content. Double curly braces {{ ... }}will result in rendering data from a data source, object, or variable. A curly brace with a percent sign {% ... %}will render logic.

User Data Tag Include

To render a Data Tag, include the tag in curly braces using the {{ data_tag }} format.

Hello, {{ first_name }}

"first_name": "George"

Hello, George

API Custom Data Include

To render values from custom_data in API notifications, call the data:

{{ message.custom_data.example_key }}

Your account balance is ${{ message.custom_data.balance }}

{
  "app_id": "5eb5a37e-b458-11e3-ac11-000c2940e62c", 
  "template_id": "be4a8044-bbd6-11e4-a581-000c2940e62c",
  "custom_data": { "balance": "23.40" }
}


Your account balance is $23.50

Property Include

As well as custom-defined data tags, you can also include many predefined properties by using the same curly braces method as used for tag substitution. For example, the subscription's email address can be included like so:

Your current email address is {{ subscription.email }}

As well as properties relating to subscriptions and users, you can also use properties specific to your OneSignal app and organization.

For a full list of the properties available to use with liquid syntax, please see Message Personalization.

Logic Tags

Logic tags are used to create conditions for displaying content, and use the curly brace percent sign syntax:

{% ... %}

The content inside of these tags do not produce any visible output when the template is rendered. This lets you assign variables and create conditions or loops without printing any of the Liquid logic in the content.

{%- assign level = level -%}
{% if level == '2' -%}
Congrats on making it past the first level, {{ first_name }}!
{%- elsif level > '2' -%}
Congrats on making it to level {{ level}}, {{ first_name }}!
{%- else -%}
{{ first_name }}, come back to beat the first level!
{%- endif -%}

"first_name": "George", "level": "3"

Congrats on making it to level 3, George!

Filters

You can apply Liquid filters to adjust how the data is displayed. Filters are added after the variable or object, and are separated by a pipe symbol:

{{ variable | filter }}

Default Value

The most common use case for a filter is to assign a default value.

Hello {{ first_name | default: 'there' }}.

If the Data Tag for first_name is blank or does not exist, the default value will be rendered instead.

Hello there.

Additionally, you can specify the default, which will show its value if the input is nil, false, or empty.

{{ product_price | default: "2.99" }}

2.99

Dates

The date filter converts a timestamp into another date format. The format for this syntax is the same as strftime. The input uses the same format as Ruby’s Time.parse.

Set dates as a unix timestamp in seconds with Data Tags. This allows for use of both liquid syntax personalization and segmentation with Time Operators. For example, a tag might look like: bill_due : 1687968776

{{ bill_due | date: "%a, %b %d, %y" }}

Wed, Jun 28, 23

{{ event_date | date: "%Y" }}

2023

Date formatting works on strings if they contain well-formatted dates.

{{ "March 14, 2016" | date: "%b %d, %y" }}

Mar 14, 16

To get the current time, pass the special word now (or today) along with the date filter.

This message was sent at {{ "now" | date: "%Y-%m-%d %H:%M" }}.

This message was sent at 2022-11-02 14:39.

📘

Current Time is based on when the message is rendered

The current time will be rendered in the message based on when the message is sent to the recipient. If you are testing the message, you will see the current time as when the test message was sent.

Capitalize

This filter makes the first character of a string capitalized and converts the remaining characters to lowercase.

{{ "my GREAT title" | capitalize }}

My great title

Round

This filter rounds a number to the nearest integer, or, if a number is passed as an argument, to that number of decimal places.


{{ 1.2 | round }}
{{ 2.7 | round }}
{{ 183.357 | round: 2 }}

1
3
183.36

Pluralize

This filter returns the singular or plural form of a string based on a given number. The number must be a whole number and can be provided as a string. Both the singular and plural forms of a string must be provided.

{{ 1 | pluralize: 'singular', 'plural' }}
{{ 2 | pluralize: 'singular', 'plural' }}
1 {{ 1 | pluralize: 'person', 'people' }}
2 {{ 2 | pluralize: 'person', 'people' }}
2 {{ '2' | pluralize: 'person', 'people' }}

singular
plural
1 person
2 people
2 people

Conditional Logic

Display different content depending on the presence of data.

Operators

In conditional statements, you have logical operators available to use. The operators available are:

  • == 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, and for the presence of a string in an array of strings.

Order of operations

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.

{% if true or false and false %}
  This evaluates to true, since the `and` condition is checked first.
{% endif %}

if, elsif, else

You can use logical operators such as if, else, and elsif as control flow tags to create conditions that decide whether blocks of Liquid code get executed.

{%- assign userLang = user.language -%}
{% if userLang  == 'es' -%}
Hola {{ first_name }}!
{%- elsif userLang  == 'fr' -%}
Bonjour {{ first_name }}!
{%- else -%}
Hello {{ first_name }}!
{%- endif %}

language: "fr", tags: {"first_name": "George"}

Bonjour George!

unless

The opposite of if executes a block of code only if a certain condition is not met. unless might be similar to using the != not equal operator.

{% unless level == "1" %}
  Great job getting past the first level!
{% endunless %}

Iteration

for loops

Repeatedly executes a block of code. For a full list of attributes available within a for loop, refer to the for loop object.

{% for product in message.custom_data.products %}
  - {{ product.name }}
{% else %}
  Sorry, we're sold out of all products.
{% endfor %}

{
  "app_id": "5eb5a37e-b458-11e3-ac11-000c2940e62c", 
  "template_id": "be4a8044-bbd6-11e4-a581-000c2940e62c",
  "custom_data": { 
    "products": [
      { "name": "Sweater" },
      { "name": "Hat" },
      { "name": "Shirt" }
    ]
  }
}

// if message.custom_data.products has a value
- Sweater
- Hat
- Shirt

// if message.custom_data.products is empty
Sorry we're sold out of all products

🚧

Performance and limitations of using for loops

While powerful and flexible, the usage of for loops in liquid syntax can lead to poor notification delivery performance in certain rare cases. Be mindful of your usage of for loops. Also note that we prevent the usage of for loops in a few Push Channel fields: contents, headings, subtitle, apns_alert, and url

limits & offsets

Limits the loop to the specified number of iterations. For example, if you only want to show 4 products in a message, you could use Limits and Offsets to specify the number of products shown.

great_numbers = [1,2,3,4,5,5]

{% for number in great_numbers limit:2 %}
  {{ number }}
{% endfor %}

1 2

To begin the loop at the specified index, add an offset value:

great_numbers = [1,2,3,4,5,5]

{% for number in great_numbers limit: 3 %}
  {{ number }}
{% endfor %}

{% for number in great_numbers limit: 3 offset: continue %}
  {{ number }}
{% endfor %}

1 2 3
4 5 6

where

Creates an array including only the objects with a given property value, or any truthy value by default.

In this example, assume you have a list of products and you want to show your kitchen products separately. Using where, you can create an array containing only the products that have a type of kitchen.

products = [
  {name:"Vacuum", type:"electronics"},
  {name:"Spatula", type:"kitchen"},
  {name:"Television", type:"electronics"},
  {name:"Garlic press", type:"kitchen"}
]

All products:
{% for product in products %}
- {{ product.name }}
{% endfor %}

{% assign kitchen_products = products | where: "type", "kitchen" %}

Kitchen products:
{% for product in kitchen_products %}
- {{ product.name }}
{% endfor %}

All products:
- Vacuum
- Spatula
- Television
- Garlic press

Kitchen products:
- Spatula
- Garlic press

FAQ

Why is substitution not working?

Property substitution doesn't work for In-App Messages at this time.

Tag substitution does not work when an in-app message is sent to test users via the "Send Test Message" buttons.

Tag substitution will not work if you have spaces, periods, or "dots" in tag keys. Only use alphanumeric characters and an underscore ("_") or hyphen ("-") in your tag keys if needed.

Tag substitution will not work in the previews. You need to send the actual message.

How to control whitespace and newlines?

Whitespace control is a part of Liquid where you can add hyphens - inside of the Liquid syntax {{- ... -}} and {%- ... -%} to remove newlines and whitespace on the side of the Liquid code that generates it.

For example, with this syntax, you may see a new line in the notification above and below the text.

{% assign name = "Jon" %}
{{ name }}
{% unless level == "1" %}
Great job getting past the first level!
{% endunless %}


Jon

Great job getting past the first level!

By including hyphens -, you can strip the whitespace. See Whitespace control for more details.

{% assign name = "Jon" -%}
{{ name -}}
{% unless level == "1" %}
Great job getting past the first level!
{%- endunless %}

Jon
Great job getting past the first level!

What if I pass user-generated content into my messages?

If you have an app that takes user-generated text and puts it into a message, sometimes that text can contain invalid liquid characters. In this case, it is best to wrap your user-generated content within the "raw" syntax.

For example:

{
  "contents": { 
    "en": "{% raw %} Your user-generated content with invalid characters like {{ {% endraw %}" 
  }
}

Updated 2 months ago