Create notification

📘

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:

• Send to Segments
• Send to Users Based on Filters
• Send to Specific Devices

🚧

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.

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:

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.

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
}