Using Liquid

This article will show how you can use a variety of user attributes to dynamically insert personal information into your messaging.

Liquid is an open-source template language developed by Shopify and written in Ruby. You can use it in Braze to pull user profile data into your messages and customize that data. For example, you can use Liquid tags to create conditional messages, such as sending different offers based on a user’s subscription anniversary date. Additionally, filters can manipulate data, like formatting a user’s registration date from a timestamp into a more readable format, such as “January 15, 2022.” For further details on Liquid syntax and its capabilities, refer to Supported personalization tags.

How it works

Liquid tags act as placeholders in your messages that can pull in consented information from your user’s account and enable personalization and relevant messaging practices.

In the following block, you can see that a dual usage of a Liquid tag to call the user’s first name, as well as a default tag in the event that a user would not have their first name registered.

1
Hi {{ ${first_name} | default: 'Valued User' }}, thanks for using the App!

To a user named Janet Doe, the message would appear to the user as either:

1
Hi Janet, thanks for using the App!

Or…

1
Hi Valued User, thanks for using the App!

Supported values to substitute

The following values can be substituted into a message, depending on their availability:

• Basic user information (for example, first_name, last_name, email_address)
• Custom attributes
  • Nested custom attributes
• Custom event properties
• Most recently used device information
• Target device information

You can also pull content directly from a web server through Braze Connected Content.

Using Liquid

Using Liquid tags, you can elevate the quality of your messages by enriching them with a personal touch.

Liquid syntax

Liquid follows a specific structure, or syntax, that you’ll need to keep in mind as you’re crafting dynamic personalization. Here are a few basic rules to keep in mind:

1. Use straight quotes in Braze: There is a difference between curly quotes (’ ‘) and straight quotes (' '). Use straight quotes (' ') in your Liquid in Braze. You may see curly quotes when copying and pasting from certain text editors, which can cause issues in your Liquid. If you’re inputting quotes directly into the Braze dashboard, you’ll be fine!
2. Brackets come in pairs: Every bracket must both open and close { }. Make sure to use curly brackets!
3. If statements come in pairs: For every if, you need an endif to indicate the if statement has ended.

Default attributes and custom attributes

If you include the following text in your message: {{${first_name}}}, the user’s first name (pulled from the user’s profile) will be substituted when the message is sent. You can use the same format with other default user attributes.

If you would like to use the value of a custom attribute, you must add the namespace “custom_attribute” to the variable. For example, to use a custom attribute named “zip code”, you would include {{custom_attribute.${zip code}}} in your message.

Inserting tags

You can insert tags by typing two open curly brackets {{ in any message, which will trigger an auto-completion feature that will continue to update as you type. You can even select a variable from the options that appear as you type.

If you’re using a custom tag, you can copy and paste the tag into whatever message you desire.

Inserting pre-formatted variables

You can insert pre-formatted variables with defaults through the Add Personalization modal located on the top-right of any templated text field.

The modal will insert Liquid with your specified default value at the point that your cursor was. The insertion point is also specified by the preview box, which has the before and after text. If a block of text is highlighted, the highlighted text will be replaced.

Assigning variables

Some operations in Liquid require you to store the value you want to manipulate as a variable. This is often the case if your Liquid statement includes multiple attributes, event properties, or filters.

For example, let’s say you want to add two custom data integers together.

Incorrect Liquid example

You can’t use:

1
{{custom_attribute.${one}}} | plus: {{custom_attribute.${two}}}

This Liquid doesn’t work because you can’t reference multiple attributes in one line; you need to assign a variable to at least one of these values before the math functions take place. Adding two custom attributes would require two lines of Liquid: one to assign the custom attribute to a variable, and one to perform the addition.

Correct Liquid example

You can use:

1
2
{% assign value_one = {{custom_attribute.${one}}} %}
{% assign result = value_one | plus: {{custom_attribute.${two}}} %}

Tutorial: Using variables to calculate a balance

Let’s calculate a user’s current balance by adding their gift card balance and rewards balance:

First, use the assign tag to substitute the custom attribute of current_rewards_balance with the term “balance”. This means that you now have a variable named balance, which you can manipulate.

1
{% assign balance = {{custom_attribute.${current_rewards_balance}}} %}

Next, we’ll use the plus filter to combine each user’s gift card balance with their rewards balance, signified by {{balance}}.

1
2
{% assign balance = {{custom_attribute.${current_rewards_balance}}} %}
You have ${{custom_attribute.${giftcard_balance} | plus: {{balance}}}} to spend!