Message Personalization

Send messages that are personalized to individual customers

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.


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

  1. The content of the message, and
  2. 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:

  • Data Tags: 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 }}")

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 are sending transactional messages, the steps are:

  1. Create a template for each type of transactional message in the OneSignal dashboard
  2. Use Liquid Syntax to get the values from custom_data into the message content. Use {{message.custom_data.[data name]}} in your message to reference the data.
  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]"]