Personalizing messages helps users connect more with your app and website. Common examples are putting the person's name or abandoned cart item in the message.

Sending messages that are personalized to the recipient can increase engagement and revenue. In this guide we'll show you how to tailor your message content to individual customers in OneSignal.

Overview

When you're starting to create personalized messages, you'll want to consider both:

The content of the message, and
When to send the message

Message content is how you tailor the message to best suit the individual customer you are messaging. A basic way to customize messages would be including their name. Or, you can get more complex by wording the content differently depending on the preferences of the recipient.

You can control the timing of when a message gets sent by adjusting the schedule when Sending Messages, sending via Journeys, Sending Transactional Emails, or setting up Automated Messages.

For example, you might want to consider sending out marketing messages at a particular time of day. Or you might want to send out a purchase confirmation immediately after the payment is processed.

How to Personalize Message Content

Use Liquid Syntax to insert custom variables of information into the content of your messages. Variables can be added using:

Properties: User and device properties stored within predefined fields in OneSignal (e.g. Subscription Push Token, User Language, etc.)
Data Tags: Custom defined user-specific data stored within OneSignal (i.e. "Hello, {{ first_name | 'friend' }}!"
Custom Data: user-specific data stored in your database (i.e. "Receipt for order {{ message.custom_data.order_id }}")

Properties

Many user and subscription properties, such as External ID, language and email address are stored in predefined fields within OneSignal.

To utilize these for message personalization, you can include them in a message using Liquid Syntax, for example: "Your current email address is {{ subscription.email }}"

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

User Properties:

user.language: The language of the user, currently same as player
user.tags: The tags of the user, currently same as player

Subscription Properties:

subscription.external_id: The external id of the player
subscription.email: The email of the player (when an email)
subscription.phone_number: The phone number of the player (when an SMS)
subscription.push_token: The push token of the player (when a push)
subscription.language: The language code of the player
subscription.tags: The tags of the player

Message Properties:

message.id: The id of the message
message.custom_data: The message's custom_data

Template Properties:

(Only exists if the notification was built from a template)

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

Application Properties:

app.id: The id of the application the notification is sent under
app.name: The name of the application the notification is sent under

Organization Properties:

(Only exists if the app the notification was sent under is itself under an organization.)

org.id: The id of the organization (i.e. Organization.id)
org.name: The name of the organization (i.e. Organization.name)

Data Tags

Data Tags are key: value pairs of String data that you can define for each of your users in OneSignal, and you can use them to segment and personalize messages.

Data Tags that work best for personalization are pieces of information about the user that do not need to change for each message. For example,first_name, level, amount_spent, last_viewed_item, and discount_amount. For examples of use cases and techniques for adding Data Tags to messages, see our Data Tags guide.

Custom Data (API Only)

Adding custom_data to a create notification API request is a perfect way to get transactional data into messages you want to send to a single user in response to an event. Examples of transactional messages might be abandoned cart, payment due, updated settings, order confirmation, and more.

If you'll be sending transactional messages, the steps are:

Create a template for each type of transactional 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. Please see an example below:

params = {
  "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://.."}]
}

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]"]
}