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:

1. The message content: What data do you want to display and where is that data located?
2. 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' }}!"
• 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.

1. Create a template for each type of message.
2. Use Liquid Syntax with format message.custom_data.key to get the associated value into the message content.
3. 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.

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.