​
How personalization works

Personalization is powered by Liquid syntax, a templating language that lets you inject values into message fields. You can personalize messages using:
  • Data feeds: Real-time data from your APIs.
  • Properties: Built-in user, journey, message, template, app, or org values.
  • Custom Events: Real-time user events for personalizing Journey messages.
  • Tags: Data saved in OneSignal at a per-user level.
  • API: custom_data: Custom data you pass directly into our Create Message API.
  • Dynamic content: CSV-based personalization via dashboard uploads.

​
Key considerations

Personalizing messages helps users connect deeper with your app, potentially increasing engagement and revenue. Common examples are putting the person’s name or specific information (like abandoned cart items) in the message but the use cases are endless. What is the goal? What do you want to send in the message? Examples:
  • Add a user property like name or ID
  • Show invoice or OTP
  • Send dynamic content from a CSV
Where is the data located?
  • Is the data stored in OneSignal like a property or a tag?
  • Is the data stored in your own database?
  • Do you need to pass data from your backend to OneSignal?
How do you want to send the message?
  • One-time messages: Send the message from your server or through the OneSignal dashboard?
  • Recurring messages: Using Journeys or other automated workflows?
Example:
  • Goal: Send a one-time-passcode to help a user login.
  • Data:
    • OTP stored on your backend.
    • User name store in OneSignal as a tag.
    • External ID stored in OneSignal as a property.
  • Send:
    • From your server using our REST API.
    • From an automated workflow using Journeys.
A details walkthrough of this example is available in the Verification, Magic Link, & OTP example tutorial.See more Tutorial examples below.

​
Data sources

Available options for personalizing messages.

​
Data feeds

Data Feeds are a way to pull real-time data from your APIs directly into messages at send time. Just connect a template to your data source and we will pull the data from your server and inject it into the message.

​
Properties

Predefined fields you can reference using Liquid syntax. Example: 
Hi!
Thanks for subscribing with email {{ subscription.email }}.
Your user ID is {{ subscription.external_id }}.
Properties are not available in In-App Messages or Live activities.
  • subscription.external_id: The External ID associated with the Subscription.
  • subscription.email: The email address of the email Subscription being sent the message.
  • subscription.phone_number: The phone number of the SMS Subscription being sent the message.
  • subscription.push_token: The push token of the push Subscription being sent the message.
  • subscription.language: The language code of the user.
  • subscription.unsubscribe_token: The token used to identify a subscription for unsubscribe (when an email Subscription).

​
Custom Events

Reference Custom Events within Templates used in Journeys. Depending on the Journey configuration, it may store one or more Custom Events on behalf of the user. You can use Liquid syntax to display properties of these stored events, or to conditionally display parts of your message based on the events.
​
journey.first_event
For Event-triggered Journeys, this will always be the event that caused the user to enter the Journey. Otherwise, it is the first event matched by a Wait Until condition.
{% assign event = journey.first_event %}
​
journey.last_event
The most recent Custom Event stored. If there is only one stored custom event, first_event and last_event will return the same thing.
{% assign event = journey.last_event %}
​
journey.event.most_recent_event_name
The most recent event with a given name. If the same event is used multiple times, this will return the most recent instance. Example: order_status.
{% assign event = journey.event.order_status %}
For special characters (e.g. spaces), use hash notation if the event name contains non-alphanumeric characters:
{% assign event = journey.event["order status"] %}
​
journey.all_events
Provides an array of all events stored for this Journey for the user, in the order they were received. You can use for loops to iterate over them.
{% for event in journey.all_events %}
  {{ event.name }}
{% endfor %}
first_event and last_event are shorthand for all_events[0] and all_events[-1], respectively.

​
Tags

Tags are key: value data you can set on each user. Example: 
Hi {{ first_name | default: "friend" }}!
Congrats on reaching level {{ level | default: "1" }}!
If you set first_name: Jon and level: 5 for User A and first_name: Jeff and level: 100 for User B, each will see their name and level in the message. Otherwise, they’ll see the default values.

​
API custom_data

Add personalization directly from your backend using custom_data and our Create message API. Steps:
  1. Create a template
  2. Use Liquid Syntax with format {{ message.custom_data.key }}
  3. Send API request with the custom_data object and template_id

​
Example: Flat JSON

Template
Your invoice for {{message.custom_data.product_name}} is ready.
URL: https://your-domain.com/invoice={{message.custom_data.invoice_id}}
API Request
{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "include_email_tokens": ["THE_USER_EMAIL"],
  "custom_data": {
    "invoice_id": "463246732",
    "product_name": "Widget"
  }
}
Customer sees:
  • “Your invoice for Widget is ready.”
  • The final URL: https://your-domain.com/invoice=463246732

​
Example: Array data

Template
Your {{message.custom_data.cart_items[0].item_name}} is waiting for you!
Image: {{message.custom_data.cart_items[0].image_url}}
API Request
{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "include_email_tokens": ["THE_USER_EMAIL"],
  "custom_data": {
    "cart_items": [
      {
        "item_name": "sweater",
        "img_url": "https://.../sweater.png"
      },{
        "item_name": "socks",
        "img_url": "https://.../socks.png"
      }
    ]
  }
}
Customer sees:
  • “Your sweater is waiting for you!”
  • The image: https://.../sweater.png

​
Example: Bulk personalization

To personalize a single message for many users in one request:
Template
{% assign eid = message.custom_data.users[subscription.external_id] %}
Hi {{ eid.first_name }}, you have {{ eid.points }} points. Your level is {{ eid.level }}.
API Request
{
  "app_id": "YOUR_APP_ID",
  "template_id": "YOUR_TEMPLATE_ID",
  "include_aliases": {
    "external_id": ["user123", "user456"]
  },
  "custom_data": {
    "users": {
      "user123": { "first_name": "John", "points": "150", "level": "Gold" },
      "user456": { "first_name": "Sarah", "points": "200", "level": "Platinum" }
    }
  }
}
Customer sees:
  • “Hi John, you have 150 points. Your level is Gold.”
  • “Hi Sarah, you have 200 points. Your level is Platinum.”

​
Dynamic Content

Using a CSV of data, you can upload this into the OneSignal dashboard to customize the campaign based on per-user data. See Dynamic Content for more details.

​
Tutorials

Verification, Magic Link, & OTP example tutorial

Send verification emails, magic links via SMS, One Time Passwords or custom URLs.

Abandoned cart content

Send lists of data to users like in an abandoned cart or leaderboard.

Transactional messages

Send any type of transactional message across any channel.

In-app message examples

Display personalized in-app messages based on tags.