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.

When creating personalized messages, consider:

The message content: What data do you want to display and where is that data located?
How to send the message: Is this triggered from your server or through the OneSignal dashboard?

For example, you might want to send a one-time-passcode with a link generated from your backend. Using our API and custom_data is a great way to do this, see Example: Verification, Magic Link, OTP. You may want to send an abandoned cart reminder or list of new inventory. Depending on how you can access this data, we will discuss the options available to get it in front of your users.

How to personalize message content

Using Liquid Syntax, you can insert custom variables of information into your messages. Variables can be added using:

Properties: User properties stored within predefined fields in OneSignal (e.g. language, email address, country, External, etc.)
Data Tags: Custom user-specific data stored within OneSignal i.e. "Hello, {{ first_name | 'friend' }}!" where first_name is the tag key that will get substituted with the tag's value.
Custom Data: Data stored in your database can be include in your API Requests (i.e. "Receipt for order {{ message.custom_data.order_id }}")
Dynamic Content: A CSV of data you can upload into your messages through the dashboard.

Properties

You can inject the predefined OneSignal subscription, message, template, and application properties into messages by simply referencing them with the associated name spaces in your Liquid Syntax. For example, your email message can say: "Your current email address is {{ subscription.email }} and your User ID is {{ subscription.external_id }}".

Please note that properties are not available in In-App Messages or Live activities.

Subscription Properties

See Subscriptions for details.

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).

Message Properties:

message.id: The OneSignal message ID.
message.custom_data: The message's custom_data.

Template Properties:

Only exists if the message was build with Templates.

template.id: The OneSignal template ID.
template.name: The name of the template.

Application Properties:

See Apps & Organizations for details.

app.id: The OneSignal App ID from which the message was sent.
app.name: The name of the OneSignal application from which the message was sent.

Organization Properties:

See Apps & Organizations for details.

org.id: The OneSignal organization ID of the OneSignal app that sent the message.
org.name: The name of the OneSignal organization of the OneSignal app that sent the message.

Data tags

Data Tags are key: value pairs of String data that you can define for each of your users. Common examples:first_name, level, amount_spent, last_viewed_item, and discount_amount.

For example, if you set the tag first_name: Jon for userA and first_name: Jeff for userB. Then send a message with: "Hi {{ first_name }} here are some updates you missed!" then userA would see: "Hi Jon here are some updates you missed!" and userB would see "Hi Jeff here are some updates you missed!".

Custom data (API Only)

Adding custom_data to a create notification API request is a perfect way to get your custom data into messages. Common examples are Transactional Messages like abandoned cart, payment due, updated settings, order confirmation, and more.

Create a template for each type of message.
Use Liquid Syntax with format message.custom_data.key to get the associated value into the message content.
Reference the appropriate template ID in your create notification API request and send additional unique user data to be displayed in the message within the custom_data parameter.

Example: Custom data with flat JSON object

Template: Your invoice number is {{message.custom_data.invoice_id}}.

{
  "app_id": "5eb5a37e-b458-11e3-ac11-000c2940e62c", 
  "template_id": "45d24a11-f739-4878-a15c-f32535547e90",
  "include_email_tokens": ["[email protected]"],
  "custom_data": { "invoice_id": "463246732" }
}

Customer sees: "Your invoice number is 463246732."

Example: Custom data with array data

Template Content: Your {{message.custom_data.cart_items[0].item_name}} is waiting for you!

Template Image: {{message.custom_data.cart_items[0].image_url}}

{
  "app_id": "5eb5a37e-b458-11e3-ac11-000c2940e62c", 
  "template_id": "45d24a11-f739-4878-a15c-f32535547e90",
  "include_email_tokens": ["[email protected]"],
  "custom_data": { 
    "cart_items": [
      {
        "item_name": "sweater",
        "img_url": "https://.."
      },{
        "item_name": "socks", 
        "img_url": "https://.."
      }
    ]
  }
}

Customer sees: "Your sweater is waiting for you!" with the image url associated with the first object in the array.

Example: Utilizing Custom Data in bulk API calls

To send messages utilizing custom data in bulk via the API, you will need to add each user's custom data as an object with a key that correlates to the alias you are using to target those users (see the Create message API for more details on targeting by alias). For example:

  "custom_data": {
    "users": {
      "external-id-1": {
        "first_name": "John",
        "points": "150",
        "level": "Gold"
      },
      ...

Utilizing this method allows you to use different data for each user, without storing all of that data in Tags, and allows for scaling to suit your needs (please note that there is a 20,000 alias limit per API request).

To ensure that the custom data is reflected in the message, your template will need to include a reference to the user's alias as part of the template's custom data liquid syntax, as demonstrated below:

{% assign user_data = message.custom_data.users[subscription.external_id] %}
Hello {{ user_data.first_name }}, you earned {{ user_data.points }} points today! Your new level is {{ user_data.level }}.

In the API request, ensure that there is a users object which contains an object for each user where the key for that object is the alias being targeted in this call, and the object itself contains the key/value pairs for each of the necessary custom data points referenced in your template:

{
  "app_id": "your-app-id",
  "template_id": "your-template-id",
  "include_aliases": { 
    "external_id": ["user123", "user456", "user789"]
  },
  "custom_data": {
    "users": {
      "user123": {
        "first_name": "John",
        "points": "150",
        "level": "Gold"
      },
      "user456": {
        "first_name": "Sarah",
        "points": "200", 
        "level": "Platinum"
      },
      "user789": {
        "first_name": "Mike",
        "points": "75",
        "level": "Silver"
      }
    }
  }
}

More examples:

Abandoned Cart Content - send us a custom_data object and use a for-loop to display within the message.
Example: Verification, Magic Link, OTP - generate a user's login credentials on your own server and pass them into the message.

Your CRM/Internal System (API Only)

If you don't want to use OneSignal's Data Tags, or build templates in the OneSignal dashboard, you can build the entire content of the message in your system of choice and pass the content directly into the appropriate fields in the create notification API request.

params = {
  "app_id" => "5eb5a37e-b458-11e3-ac11-000c2940e62c", 
  "email_subject" => "Welcome to Melrose Place",
  "email_body" => "<html><head>Welcome to the neighborhood</head><body><h1>Hi Nick! Welcome to Melrose Place</h1><h4>Learn more about your new neighborhood</h4><hr/>Thanks for subscribing. We can't wait to surprise you with details about your neighborhood.</p><p><small><a href='[unsubscribe_url]'>Unsubscribe</a></small></p></body></html>",
  "include_email_tokens" => ["[email protected]"]
}

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.