Sends notifications to your users

📘

OneSignal's Hiring!

If you love OneSignal and would like to work here, let us know! Feel free to browse our open positions and apply on our careers page: https://onesignal.com/careers

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_external_user_ids 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 User Ids and the include_external_user_id 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
emailvalue = email address

Only for sending Push Notifications

Use this for targeting push subscribers associated with an email set with all SDK setEmail methods

To send emails to specific email addresses use include_email_tokens parameter

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.
  • ANDs have priority over ORs.
  • 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.

🚧

You may only use one method of targeting users

filters cannot be combined with included_segments, include_external_user_ids 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 Devices

You may also target specific devices. Targeting devices is typically used in two ways:

  1. For transactional notifications that target individual users.

  2. For apps that wish to manage their own segments, 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_player_idsarray_stringSpecific player_ids to send your notification to.

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

Limit of 2,000 entries per REST API call
include_external_user_idsarray_stringTarget 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_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_external_user_ids 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_external_user_ids 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_external_user_ids 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_external_user_ids 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_external_user_ids 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_external_user_ids 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_external_user_id channels

External User IDs can be associated with Push, Email, or SMS records, you must set channel_for_external_user_ids to "push" or "email" or "sms" when sending to that channel.

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

{
"include_external_user_ids": ["external_user_id_on_push_email_sms"],
"channel_for_external_user_ids": "email"
}

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

{
"include_external_user_ids": ["external_user_id"],
"channel_for_external_user_ids": "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 browser 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.
channel_for_external_user_idsstring"push" or "email" or "sms"

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