Message Personalization

Send messages that are personalized to individual customers

Overview

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: user-specific data stored in your database you can 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:

  • 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
  • subscription.unsubscribe_token: The token used to identify a subscription for unsubscribe (when an email)

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)

Message Properties:

(Only exists for the Event Webhook body, url, and headers)

  • message.id: The id of the message
  • message.name: The message's name
  • message.title: The message's title, available for push and email message events
  • message.contents: The message's title, available for push and sms message events
  • message.template_id: The message's template id if it was created from a template

Event Properties:

(Only exists for the Event Webhook body, url, and headers)

  • event.id: The id of the message
  • event.kind: The kind of message event that was sent ex. 'message.push.send'
  • event.external_user_id: The external_id the message event is associated with
  • event.subscription_id: The subscription_id the message event is associated with
  • event.subscription_device_type: The device type of the subscription that the message event was sent to
  • event.datetime: The date time that the event was processed ex. '2023-11-17T00:32:36+00:00'

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:

  1. Create a template for each type of transactional 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. 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]"]
}

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.