Sending personalized and timely messages to individuals or small groups of users is paramount to providing a good customer experience and keeping the lines of communication opened with your users.

Transactional push notifications, emails, and SMS are great for sharing custom data from your server, whether that is One-Time Passcodes (OTP), billing related updates, task/event reminders, or simply saying "Thanks for performing this action!" (whatever that action may be).

This guide explains how to send transactional messages to individuals with custom data from your server.

Identifying users

First, you need a way to identify users within OneSignal. Best practice is to set the External ID which relates to how you identify users in your database or CRM. See Users and Aliases for details.

OneSignal allows you to track up to 20 different aliases per user, so if your engineering team tracks users via a database while your marketing team tracks users with a different system or ID (like a facebook_id) you can use any of these to target users with messages.

Also, if you already have the email address or phone number, you can use these to send emails and SMS respectively.

Sending Messages

Using the Create message API, you can send push notifications, emails, and SMS targeting users individually via their aliases, emails, or phone numbers.

Send to aliases

All message channels support sending via an alias. You can include up to 2000 aliases per request.

Using include_aliases, you can target the recommended external_id alias like so:

{
  "app_id": "YOUR_APP_ID",
  "include_aliases": {"external_id": ["userA"]},
  "contents": {"en": "English Message"},
  "target_channel": "push"

}

If you set custom alias' like facebook_id, you can use your set label and include the user IDs you want to target.

{
  "app_id": "YOUR_APP_ID",
  "include_aliases": {"facebook_id": ["friendA"]},
  "contents": {"en": "English Message"},
  "target_channel": "email"

}

If you want to send to specific Subscriptions, you can also use the include_subscription_ids property.

{
  "app_id": "YOUR_APP_ID",
  "include_subscription_ids": ["1dd608f2-c6a1-11e3-851d-000c2940e62c"],
  "contents": {"en": "English Message"},
  "target_channel": "email"

}

Send to email addresses

You can only send emails to email addresses, we provide the include_email_tokens property.

{
  "app_id": "YOUR_APP_ID",
  "include_email_tokens": ["[email protected]"],
  "email_subject": "Welcome to Cat Facts!",
  "email_body": "<html><head>Welcome to Cat Facts</head><body><h1>Welcome to Cat Facts</h1><h4>Learn more about everyone\'s favorite furry companions!</h4><hr/><p>Hi Nick,</p><p>Thanks for subscribing to Cat Facts! We can\'t wait to surprise you with funny details about your favorite animal.</p><h5>Today\'s Cat Fact (March 27)</h5><p>In tigers and tabbies, the middle of the tongue is covered in backward-pointing spines, used for breaking off and gripping meat.</p><a href=\'https://catfac.ts/welcome\'>Show me more Cat Facts</a><hr/><p><small>(c) 2018 Cat Facts, inc</small></p><p><small><a href=\'[unsubscribe_url]\'>Unsubscribe</a></small></p></body></html>"
}

Send to phone numbers

You can only send sms and mms to phone numbers, we provide the include_phone_numbers property.

{
  "app_id": "YOUR_APP_ID",
  "include_phone_numbers": ["+15555555555"],
  "contents": {"en": "English Message"}
}

Adding custom data

You can personalize messages for specific users by including custom_data from your server into the message. Other options available, see Message Personalization for details.

Steps to adding Custom Data:

Create a Template which is a reusable message. Templates can be created through our dashboard or Create template API.
Use Liquid Syntax within the template to define the variables.
Reference the template_id and custom_data within your Create message API request.

{
  "app_id": "YOUR_APP_ID",
  "include_aliases": {"external_id": ["userA"]},
  "template_id": "8458af75-4da2-4ecf-afb5-f242a8926cc3",
  "custom_data": {"order_id": 123, "currency": "USD", "amount": 25}
}

Example: One-Time Passcode (OTP)

Setup user identification. This usually happens within the frontend SDK when the user logs into the app or site. If you are sending emails and/or SMS, then all you need is the email address or phone number.

Create a Template that will be used for your message. The template message for example can be something like:

Your verification code is {{ message.custom_data.verification_code }}

Generate the verification_code on your server when the user requests access.

Input the verification_code value into the API request. For example:

{
  "app_id": "YOUR_APP_ID",
  "include_aliases": {"external_id": ["userA"]},
  "template_id": "8458af75-4da2-4ecf-afb5-f242a8926cc3",
  "custom_data": {"verification_code": verification_code}
}

If you don't want to use templates and custom_data you can input the variable value directly into the message with string concatenation. For example:

{
  "app_id": "YOUR_APP_ID",
  "include_aliases": {"external_id": ["userA"]},
  "contents": {"en": "Your verification code is " + verification_code}
}