Personalize with properties

Use properties (such as Tags and identifiers like External ID) to personalize messages and delivery payloads with Liquid syntax. OneSignal renders Liquid placeholders at send time, using data already stored on the user, subscription, Journey, message, template, app, or organization. You can use this data to personalize messages, Journey webhooks, and Event Streams.

When to use property personalization

Use property personalization to render content at send time using data that already exists in OneSignal—most commonly Tags, External ID, and subscription fields like email or phone number. This is the right approach when:

The data is already stored in OneSignal
You want Liquid placeholders replaced automatically when the message sends
You don’t need to fetch or compute fresh data at delivery time

If the value must be fetched or computed at send time (for example, live pricing or inventory), use Data Feeds or our API with custom_data.If the value comes from the event that caused a user to enter or progress through a Journey, use Custom Event personalization.

Channel support

Each channel supports specific property types and fields.

Email
Push
SMS
In-app messages
Live Activities

Supports User & Subscription properties in:

Subject, Reply-to, and Pre-header
Message body
HTML attributes (for example: <img src="{{ image_url }}" />)
Button actions (URLs, mailto, etc.)

Supports User & Subscription properties in:

Title (headings), Subtitle, Body (contents)
Image URL
Launch URL: https://example.com/{{last_category_viewed}}

The data (additional data) field does not support Liquid syntax.

Supports User & Subscription properties in:

Message body (contents)

Only support Tag substitution. Properties, Custom Events, and other data sources are not available at this time.

Tags must be set before the user starts a new app session.
Tag substitution may not appear when using test-send flows.

Block editor: Text, Button, and Image blocks
HTML editor: Text elements and attributes (src, href, action, data)

Supports User & Subscription properties in:

event_updates
contents
headings

How property personalization works

OneSignal replaces Liquid placeholders with the corresponding property values for the user and subscription being messaged.

Liquid

Hi {{ first_name | default: "friend" }}!
Congrats on reaching level {{ level | default: "1" }}!

If a user has tags first_name: Jon and level: 5, they see:

Text

Hi Jon! 
Congrats on reaching level 5!

If a user has no tags set, they see the default values instead.

Property Liquid reference

Use this section to look up the exact object and field names available in Liquid.

User & Subscription properties

Use user for user-level data. Use subscription when you need channel-specific values like email address or phone number.

The Tags of the User. You can reference the tags in several ways:

Use the key directly or place the key after tags
Example tags set: first_name: Jon, level: 5

Liquid

Your first name is {{ first_name }}.
Your first name is {{ user.tags.first_name }}.
Your level is {{ level }}.
Your level is {{ user.tags.level }}.

Iterate over tags with for-loop syntax. This example outputs key:value pairs separated by commas.

Liquid

{% for tag in user.tags %}
{{ tag[0] }}: {{ tag[1] }}
{% unless forloop.last %}, 
{% endunless %}{% endfor %}

The language code of the user.

Liquid

Current language set: {{ user.language }}

The country code of the user.

Liquid

Current country set: {{ user.country }}

The External ID of the User.

Liquid

Your user ID is {{ user.external_id }}.
Your user ID is {{ subscription.external_id }}.

The OneSignal ID of the User.

Liquid

Your OneSignal user ID is {{ user.onesignal_id }}.

The email address of the email Subscription being messaged.

Liquid

Thanks for subscribing with email {{ subscription.email }}.

The phone number of the SMS Subscription being messaged.

Liquid

Thanks for subscribing with phone number {{ subscription.phone_number }}.

The Subscriptions of the User.

Iterate over subscriptions with for-loop syntax.
This example outputs each subscription’s token and ID separated by commas.

JSON

{
  "subscriptions": "{% for subscription in user.subscriptions %}{% if subscription.subscription_token %}{{ subscription.subscription_token }}: {{ subscription.id }}{% unless forloop.last %}, {% endunless %}{% endif %}{% endfor %}"
}

The token used with the Unsubscribe email with token API.

Liquid

Unsubscribe: https://your-domain.com/unsubscribe?token={{ subscription.unsubscribe_token }}

Journey properties

The journey object lets you reference the Journey name or access Custom Event Personalization for the Journey.

The name of the Journey.

JSON

{
  "journey_name": "{{ journey.name }}"
}

Message properties

The message object provides access to the message ID, name, and template ID that can be helpful for Event Streams along with access to custom_data for personalizing messages sent from your backend.

The ID of the message set by OneSignal.

JSON

{
  "message_id": "{{ message.id }}"
}

The name of the message set by you, the sender.

JSON

{
  "message_name": "{{ message.name }}"
}

The ID of the template set by OneSignal.

JSON

{
  "template_id": "{{ message.template_id }}"
}

Template properties

The template object provides access to the template ID and name about the Template used to send the message. This can be helpful for Event Streams.

The ID of the template set by OneSignal.

JSON

{
  "template_id": "{{ template.id }}"
}

The name of the template set by you, the sender.

JSON

{
  "template_name": "{{ template.name }}"
}

App and organization properties

The app and org objects provide details about the App and Organization that sent the message. This can be helpful for Event Streams.

The ID of the app set by OneSignal.

JSON

{
  "app_id": "{{ app.id }}"
}

The name of the app set by you, the owner of the app.

JSON

{
  "app_name": "{{ app.name }}"
}

The ID of the Organization set by OneSignal.

JSON

{
  "org_id": "{{ org.id }}"
}

The name of the Organization set by you, the owner of the Organization.

JSON

{
  "org_name": "{{ org.name }}"
}

Example: Abandoned cart templates using tags

This example shows how to personalize abandoned cart messages using Tags. It builds on the Abandoned Cart tutorial. Example tags set:

JSON

{
  "cart_updated": "unix_timestamp_seconds",
  "product_image": "https://i.imgur.com/ssPCfbC.png",
  "product_name": "24 Pack of Acorns",
  "product_quantity": "1",
  "product_price": "$12.99",
  "cart_items_count": "4",
  "cart_url": "https://yourdomain.com/cart"
}

Email template

Create a new email template

Navigate to Messages > Templates > New Email Template and open the Drag & Drop Editor.

Add the layout structure

Create five rows:

Rows 1, 2, and 4: one column with a Paragraph block
Row 3: four columns with HTML | Paragraph | Paragraph | Paragraph
Row 5: one column with a Button block

Starter email template for abandoned cart

Add liquid to paragraph blocks

In row 1, add:

Liquid

We're holding onto {{cart_items_count}} items in your cart, but don't wait too long, other squirrels are getting ahead!

In row 2, add a description of what the user is looking at:

Text

Currently in your cart:

In row 4, add another CTA:

Text

Checkout now while supplies last!

Display the most recent item

In row 3, configure the four columns:Column 1 (HTML block):

HTML

<img src="{{product_image}}" alt="Image" style="max-width:100%;" />

Columns 2–4 (Text blocks):

Column 2: {{product_name}}
Column 3: {{product_quantity}}
Column 4: {{product_price}}

Add the cart URL to the button

In the row 5 Button block, set the Action URL to:

{{cart_url}}

Finished base email template for abandoned cart without styling

Test & preview the template

Send a test email to yourself using the Test & preview button.

Make sure the tags are set on your email Subscription.

Style the template

Success! Now you can apply your own styling to the template. See Design emails with drag-and-drop.

Push template

Push notifications have limited space, so display one item and mention the total count. Message field: Display item and count with correct grammar using conditional statements.

Liquid

{% assign item_count = cart_items_count | plus: 0 %}
{% if item_count == 1 %}
You left {{product_name}} in your cart.
{% endif %}
{% if item_count == 2 %}
You left {{product_name}} and {{item_count | minus: 1}} more item in your cart.
{% endif %}
{% if item_count > 2 %}
You left {{product_name}} and {{item_count | minus: 1}} more items in your cart.
{% endif %}

Image field:

Liquid

{{product_image | default: "https://i.imgur.com/ssPCfbC.png"}}

Launch URL field:

Liquid

{{cart_url | default: "https://yourdomain.com/cart"}}

Preview push template personalization with Test & preview

Success! You can now create more templates and use them in the Abandoned Cart Journey.

Example: Personalize an in-app message with tags

This example shows a reward in-app message personalized with Tags. The IAM substitutes Tag values into multiple block types. In the configured message:

Text block — displays the completed level and the reward for that level
Image block — displays the image for that reward, with a default image as fallback
Button 2 text — displays the reward value, with a default of 100
Background image — set from a Tag value

In-app message editor with Tag substitution configured in text, image, and button blocks

The message renders at session start using the user’s current Tag values:

In-app message displayed to the user with values substituted from Tags

See the In-app messages tab in Channel support above for the supported blocks, attributes, and timing rules. Two reminders worth restating from there:

Tags must be set before the user starts a new app session. Tags updated mid-session don’t render in IAMs shown in that session.
Tag substitution doesn’t render in “Send Test Message” test-sends. Trigger the message from a real session to verify substitution.
Property substitution is not supported in in-app messages.

Message personalization

Overview of all personalization options in OneSignal, including when to use Custom Events vs other methods.

Using Liquid syntax

Complete Liquid reference with filters, conditionals, loops, and string manipulation.

Templates

Create and manage reusable message templates for use in Journeys.

Abandoned cart tutorial

Build an abandoned cart Journey using Tags and Properties.

Need help?Chat with our Support team or email support@onesignal.comPlease include:

Details of the issue you’re experiencing and steps to reproduce if available
Your OneSignal App ID
The External ID or Subscription ID if applicable
The URL to the message you tested in the OneSignal Dashboard if applicable
Any relevant logs or error messages

We’re happy to help!

First steps & settings

Message channels

Journeys

OneSignal AI

Audience & events

Analytics & Integrations

Privacy & Security

Personalize with properties

When to use property personalization

Channel support

How property personalization works

Property Liquid reference

User & Subscription properties

Journey properties

Message properties

Template properties

App and organization properties

Example: Abandoned cart templates using tags

Email template

Push template

Example: Personalize an in-app message with tags

Message personalization

Tags

Using Liquid syntax

Templates

Abandoned cart tutorial

​When to use property personalization

​Channel support

​How property personalization works

​Property Liquid reference

​User & Subscription properties

​Journey properties

​Message properties

​Template properties

​App and organization properties

​Example: Abandoned cart templates using tags

​Email template

​Push template

​Example: Personalize an in-app message with tags

​Related pages

Message personalization

Tags

Using Liquid syntax

Templates

Abandoned cart tutorial

When to use property personalization

Channel support

How property personalization works

Property Liquid reference

User & Subscription properties

Journey properties

Message properties

Template properties

App and organization properties

Example: Abandoned cart templates using tags

Email template

Push template

Example: Personalize an in-app message with tags

Related pages