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 Aliases & External ID 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 notification API, you can send push notifications, emails, and SMS targeting users individually via their aliases, emails, or phone numbers. See Create notification: Send to Specific Devices for all options.

For example, if you are using the recommended External ID, you can target "userA" via the external_id alias like so:

{
  "app_id": "5eb5a37e-b458-11e3-ac11-000c2940e62c",
  "include_aliases": {"external_id": ["userA"]},
  "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:

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

{
  "app_id": "5eb5a37e-b458-11e3-ac11-000c2940e62c",
  "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": "5eb5a37e-b458-11e3-ac11-000c2940e62c",
  "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": "5eb5a37e-b458-11e3-ac11-000c2940e62c",
  "include_aliases": {"external_id": ["userA"]},
  "contents": {"en": "Your verification code is " + verification_code}
}