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_aliases
parameter withfilters
. 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.
Parameter | Type | Description |
---|---|---|
included_segments | array_string | The 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_segments | array_string | Segment 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:
field | Description |
---|---|
last_session | relation = ">" or "<" hours_ago = number of hours before or after the users last session. Example: "1.1" |
first_session | relation = ">" or "<" hours_ago = number of hours before or after the users first session. Example: "1.1" |
session_count | relation = ">" , "<" , "=" or "!=" value = number sessions. Example: "1" |
session_time | relation = ">" or "<" value = Time in seconds the user has been in your app. Example: "3600" |
amount_spent | relation = ">" , "<" , or "=" value = Amount in USD a user has spent on IAP (In App Purchases). Example: "0.99" |
bought_sku | relation = ">" , "<" 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" |
tag | relation = ">" , "<" , "=" , "!=" , "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 FiltersDo not use tags for targeting individual users via a "user id". Instead use external_id or custom alias and the include_aliases targeting property. |
language | relation = "=" or "!=" value = 2 character language code. Example: "en" . For a list of all language codes see Language & Localization. |
app_version | relation = ">" , "<" , "=" or "!=" value = app version. Example: "1.0.0" |
location | radius = in meterslat = latitudelong = longitude |
country | relation = "=" value = 2-digit Country codeExample: "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 withincluded_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:
-
A user is level 10 and purchased an item
-
A user is level 10 or 20
-
A user is not VIP or is admin
-
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:
-
For transactional notifications that target individual users.
-
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.
Parameter | Type | Description |
---|---|---|
include_aliases | object | Recommended 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_ids | array_string | DEPRECATING: 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_string | Target 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_tokens | array_string | Recommended 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_numbers | array_string | Recommended 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_tokens | array_string | Not 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_uris | array_string | Not 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_ids | array_string | Not 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_ids | array_string | Not 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_ids | array_string | Not 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_ids | array_string | Not 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
channelsAliases 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 }
Parameter | Type | Platform | Description |
---|---|---|---|
isIos | boolean | iOS | Indicates whether to send to all devices registered under your app's Apple iOS platform. |
isAndroid | boolean | Android | Indicates whether to send to all devices registered under your app's Google Android platform. |
isHuawei | boolean | Huawei | Indicates whether to send to all devices registered under your app's Huawei Android platform. |
isAnyWeb | boolean | All 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 | boolean | Chrome | Indicates whether to send to all Google Chrome and Mozilla Firefox users registered under your Chrome & Firefox web push platform. |
isFirefox | boolean | Firefox | Indicates whether to send to all Mozilla Firefox users registered under your Firefox web push platform. |
isSafari | boolean | Safari | Indicates whether to send to all Apple's Safari users registered under your Safari web push platform. |
isWP_WNS | boolean | Windows | Indicates whether to send to all devices registered under your app's Windows platform. |
isAdm | boolean | Amazon | Indicates whether to send to all devices registered under your app's Amazon Fire platform. |
isChrome | boolean | ChromeApp | Indicates 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_channel | string | "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. |