Sends notifications to your users

The Create Notification method is used when you want your server to programmatically send Push Notification, Email, and SMS messages through OneSignal. You may target users in one of three ways using this method:

🚧

You may only use one method of targeting users

If a targeting parameter of one type is used, then targeting parameters from other types may not be used. For instance, you cannot use the include_aliases parameter with filters. You must use one or the other.

Send to Segments

Segments are the most common way to target large groups of devices. Sending to segments is easy: you simply specify which segments you want to target and, optionally, which ones you don't.

ParameterTypeDescription
included_segmentsarray_stringThe segment names you want to target. Users in these segments will receive a notification. This targeting parameter is only compatible with excluded_segments.

Example: ["Active Users", "Inactive Users"]
excluded_segmentsarray_stringSegment that will be excluded when sending. Users in these segments will not receive a notification, even if they were included in included_segments. This targeting parameter is only compatible with included_segments.

Example: ["Active Users", "Inactive Users"]

Send to Users Based on Filters

Filters work the same as segments without needing to create the segment first. Filters can be combined to form advanced, highly precise user targeting.

The filters parameter targets notification recipients using an array of JSON objects containing field conditions to check. The following are filter field options:

fieldDescription
last_sessionrelation = ">" or "<"
hours_ago = number of hours before or after the users last session. Example: "1.1"
first_sessionrelation = ">" or "<"
hours_ago = number of hours before or after the users first session. Example: "1.1"
session_countrelation = ">", "<", "=" or "!="
value = number sessions. Example: "1"
session_timerelation = ">" or "<"
value = Time in seconds the user has been in your app. Example: "3600"
amount_spentrelation = ">", "<", or "="
value = Amount in USD a user has spent on IAP (In App Purchases). Example: "0.99"
bought_skurelation = ">", "<" or "="
key = SKU purchased in your app as an IAP (In App Purchases). Example: "com.domain.100coinpack"
value = value of SKU to compare to. Example: "0.99"
tagrelation = ">", "<", "=", "!=", "exists", "not_exists", "time_elapsed_gt" (paid plan only) or "time_elapsed_lt" (paid plan only)
See Time Operators

key = Tag key to compare.
value = Tag value to compare. Not required for "exists" or "not_exists". Example: See Formatting Filters

Do not use tags for targeting individual users via a "user id". Instead use external_id or custom alias and the include_aliases targeting property.
languagerelation = "=" or "!="
value = 2 character language code. Example: "en". For a list of all language codes see Language & Localization.
app_versionrelation = ">", "<", "=" or "!="
value = app version. Example: "1.0.0"
locationradius = in meters
lat = latitude
long = longitude
countryrelation = "="
value = 2-digit Country code
Example: "field": "country", "relation": "=", "value": "US"

Filter Usage

  • Filter entries use "AND" by default; insert {"operator": "OR"} between entries to "OR" the parameters together.
  • "AND" has priority over "OR".
  • For performance reasons, a maximum of 200 entries can be used at a time. The 200 entries limit includes the "field" entry and "OR" entries -- each would count towards the 200 limit. Below, "Formatting Example 1" would be 2 entries and "Formatting Example 2" would be 3 entries.
  • Tag filters using an equality ("=") or "exists" operator are very fast.
  • Negation (eg. "!=" and "not_exists") is inherently more expensive to compute. Our default database indices map tags to devices, and can’t track which devices don’t have specific tags -- there are infinite tag keys which each device does not have. Upon request, it is sometimes possible for us to create a specific index on your application to address problems with negation.
  • Numeric ordering operator like "<" or ">" are slow by default. Note that upon special request, we can add a special index for specific tags to improve performance of these operators.
  • Filters on the "last_session", "session_count", and "country" fields are fast on their own or together, but when used with other filters such as tags can make the segment take longer to compute.

🚧

You may only use one method of targeting users

filters cannot be combined with included_segments, include_aliases and other device targeting options in the same request.

Formatting Filters

The power of filters comes from combining several fields and operators to precisely target your users. The following are examples of filters and how to format them:

  1. A user is level 10 and purchased an item

  2. A user is level 10 or 20

  3. A user is not VIP or is admin

  4. User's tags include key username and the user is not banned.

"filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"},
  {"field": "amount_spent", "relation": ">","value": "0"}
]
"filters": [
  {"field": "tag", "key": "level", "relation": "=", "value": "10"}, 
  {"operator": "OR"}, {"field": "tag", "key": "level", "relation": "=", "value": "20"}
]
"filters": [
  {"field": "tag", "key": "is_vip", "relation": "!=", "value": "true"},
  {"operator": "OR"}, {"field": "tag","key": "is_admin", "relation": "=", "value": "true"}
]
"filters": [
  {"field": "tag", "key": "username", "relation": "exists"},
  {"field": "tag", "key": "banned", "relation": "!=", "value": "true"}
]

Send to Specific Users and Subscriptions

You may also target specific users and their associated devices. This is typically used in two ways:

  1. For transactional notifications that target individual users.

  2. For apps that wish to manage their own user-groups, such as tracking a user's followers and sending notifications to them when that user posts.

When targeting specific devices, you may use any of the following parameters together:

🚧

You may only use one method of targeting users

Targeting specific devices cannot be combined with included_segments, filters and other device targeting options in the same request.

ParameterTypeDescription
include_aliasesobjectRecommended for transactional messages
Target specific users by aliases assigned via API. An alias can be an external_id, onesignal_id, or a custom alias.

Example: { "external_id": ["custom-external_id-assigned-by-api"]}

REQUIRED: REST API Key Authentication

Limit of 2,000 entries per REST API call.

Note: Use with target_channel to indicate you are sending a "push" or "email" or "sms".
DEPRECATING:: include_external_user_idsarray_stringDEPRECATING: Use include_aliases with external_id and target_channel instead.

Target specific devices by custom user IDs assigned via API.

Example: [“custom-id-assigned-by-api”]
REQUIRED: REST API Key Authentication

Limit of 2,000 entries per REST API call.

Note: If targeting push, email, or sms subscribers with same ids, use with channel_for_external_user_ids to indicate you are sending a "push" or "email" or "sms".
include_subscription_ids

DEPRECATING:
include_player_ids
array_stringTarget the specific subscription IDs. It is recommended to use include_aliases with external_id instead to send to all subscriptions belonging to a single user.

Does not require API Auth Key.

Example: ["1dd608f2-c6a1-11e3-851d-000c2940e62c"]

Limit of 2,000 entries per REST API call
include_email_tokensarray_stringRecommended for Sending Emails - Target specific email addresses.

If an email does not correspond to an existing user, a new user will be created.

Example: [email protected]

Limit of 2,000 entries per REST API call
include_phone_numbersarray_stringRecommended for Sending SMS - Target specific phone numbers. The phone number should be in the E.164 format. Phone number should be an existing subscriber on OneSignal. Refer our docs to learn how to add phone numbers to OneSignal.

Example phone number: +1999999999

Limit of 2,000 entries per REST API call
include_ios_tokensarray_stringNot Recommended: Please consider using include_player_ids or include_aliases instead.

Target using iOS device tokens.

Warning: Only works with Production tokens.

All non-alphanumeric characters must be removed from each token. If a token does not correspond to an existing user, a new user will be created.

Example: ce777617da7f548fe7a9ab6febb56cf39fba6d38203...

Limit of 2,000 entries per REST API call
include_wp_wns_urisarray_stringNot Recommended: Please consider using include_player_ids or include_aliases instead.

Target using Windows URIs. If a token does not correspond to an existing user, a new user will be created.

Example: http://s.notify.live.net/u/1/bn1/HmQAAACPaLDr-...

Limit of 2,000 entries per REST API call
include_amazon_reg_idsarray_stringNot Recommended: Please consider using include_player_ids or include_aliases instead.

Target using Amazon ADM registration IDs. If a token does not correspond to an existing user, a new user will be created.

Example: amzn1.adm-registration.v1.XpvSSUk0Rc3hTVVV...

Limit of 2,000 entries per REST API call
include_chrome_reg_idsarray_stringNot Recommended: Please consider using include_player_ids or include_aliases instead.

Target using Chrome App registration IDs. If a token does not correspond to an existing user, a new user will be created.

Example: APA91bEeiUeSukAAUdnw3O2RB45FWlSpgJ7Ji_...

Limit of 2,000 entries per REST API call
include_chrome_web_reg_idsarray_stringNot Recommended: Please consider using include_player_ids or include_aliases instead.

Target using Chrome Web Push registration IDs. If a token does not correspond to an existing user, a new user will be created.

Example: APA91bEeiUeSukAAUdnw3O2RB45FWlSpgJ7Ji_...

Limit of 2,000 entries per REST API call
include_android_reg_idsarray_stringNot Recommended: Please consider using include_player_ids or include_aliases instead.

Target using Android device registration IDs. If a token does not correspond to an existing user, a new user will be created.

Example: APA91bEeiUeSukAAUdnw3O2RB45FWlSpgJ7Ji_...

Limit of 2,000 entries per REST API call

Platform to Deliver To

By default, OneSignal will send to every platform (each platform equals true).

To only send to specific platforms, you may pass in true on one or more of these boolean parameters corresponding to the platform you wish to target. If you do so, all other platforms will be set to false and will not be delivered to.

🚧

Limitation Targeting include_player_ids

These parameters will be ignored if sending to devices directly with include_player_ids

For example, sending push to include_player_ids associated with Android, iOS and Web Platform:

{
  "include_player_ids": ["player_id_1", "player_id_2"],
  "isIos": true
}

This will ignore isIos and send the push message to all subscribed devices with these Player Ids.

🚧

Targeting include_aliases channels

Aliases can be associated with Push, Email, or SMS records. You must set target_channel to "push" or "email" or "sms" when sending to that channel.

For Example, sending email to an external_id associated with a push, email and sms record:

{
  "include_aliases": {
    "external_id": ["external_user_id_on_push_email_sms"]
  },
  "target_channel": "email"
}

If you want to send push to devices on a specific platform, like Android only for example:

{
  "include_aliases": {
    "external_id": ["external_user_id"]
  },
  "target_channel": "push",
  "isAndroid": true
}
ParameterTypePlatformDescription
isIosbooleaniOSIndicates whether to send to all devices registered under your app's Apple iOS platform.
isAndroidbooleanAndroidIndicates whether to send to all devices registered under your app's Google Android platform.
isHuaweibooleanHuaweiIndicates whether to send to all devices registered under your app's Huawei Android platform.
isAnyWebbooleanAll Browsers

Indicates whether to send to all subscribed web users, including Chrome, Firefox, and Safari.



You may use this instead as a combined flag instead of separately enabling isChromeWeb, isFirefox, and isSafari, though the three options are equivalent to this one.

isChromeWebbooleanChromeIndicates whether to send to all Google Chrome and Mozilla Firefox users registered under your Chrome & Firefox web push platform.
isFirefox booleanFirefoxIndicates whether to send to all Mozilla Firefox users registered under your Firefox web push platform.
isSafaribooleanSafariIndicates whether to send to all Apple's Safari users registered under your Safari web push platform.
isWP_WNSbooleanWindowsIndicates whether to send to all devices registered under your app's Windows platform.
isAdmbooleanAmazonIndicates whether to send to all devices registered under your app's Amazon Fire platform.
isChromebooleanChromeAppIndicates whether to send to all devices registered under your app's Google Chrome Apps & Extension platform. This flag is not used for web push. Please see isChromeWeb for sending to web push users.
target_channelstring"push" or "email" or "sms"Indicates if the message type when targeting with include_aliases for cases where an email, sms, and/or push subscribers have the same external user id.

Example: Use the string "push" to indicate you are sending a push notification or the string "email"for sending emails or "sms"for sending SMS.
DEPRECATED channel_for_external_user_ids string"push" or "email" or "sms"DEPRECATED: Use target_channel with include_aliases instead.

Indicates if the message type when targeting with include_external_user_ids for cases where an email, sms, and/or push subscribers have the same external user id.

Example: Use the string "push" to indicate you are sending a push notification or the string "email"for sending emails or "sms"for sending SMS.
Language