OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Notification Behavior & Payload Information

Concepts - Notification delivery and behavior

When sending notifications from OneSignal, we gather these requests and send them to Google and/or Apple whom distribute them to your users. These notifications are "held" by their servers until the device becomes online.

OneSignal uses a Custom Payload on our Mobile SDK to differentiate it from other push notifications.

Time To Live

This is the number of seconds a notification will be held by the Google (FCM) and Apple (APNs) servers before being delivered to your users if their device is not online by the time of sending.

By default, notifications will be held by the Google and Apple servers for 3 days. This means if the device does not come online within 3 days, the message will not be sent to that device.

For example, if you set TTL to 3 hours (10800 seconds) and my device does not have internet connection for 3 hours and 1 second or longer, I will not get the notification.

TTL does not remove the notification from the device once it has been received. You can use the collapse_id to achieve this. See below Notification Collapsing.

For more on setting the TTL parameter, please see Sending Push Messages

iOS Limitation - Apple will only store the most recent notification sent to a device on the APNs servers. If you send multiple notifications to an iOS device while it is offline, only the most recent notification will show when the device comes back online. More information on this in Apple's APNs Overview.

Notification Collapsing

Web Notification Collapsing

Notifications on our Web SDK are automatically collapsed. This is where the old notification is replaced with the new notification if the user has not clicked it.

For example, Notification 1 is sent and received, the user does not interact with it. Notification 2 is sent and received. Notification 1 is removed and replaced with Notification 2.

You can use the "Web Push Topic" to display more than 1 web push notification at a time on web.

Web Push Topic is any string value you can set when Sending Push Messages from the dashboard or web_push_topic API parameter.

If you do not specify the web_push_topic , each notification will be replaced by a newer notification. If you do specify web_push_topic, you can choose which notifications will be replaced and which notifications will stack.

For example:

  • Notification 1 sent with web_push_topic: "breaking-news"
  • Notification 2 sent with web_push_topic: "breaking-news"

Notification 2 will replace Notification 1.

  • Notification 3 sent with web_push_topic: "sports"
  • Notification 4 sent with web_push_topic: "weather"

Notification 2, 3 and 4 will all either be left on the screen or docked in the Notification Center.

On Chrome, a maximum of 3 notifications are displayed at any time, even if the other notifications are not related to your site or from OneSignal. This means you can only show 3 categories of notifications to your user, not counting for other notifications that might be displayed at that time.

On Firefox on Windows, many more notifications can be shown at a time (6+).

On Firefox on Mac, and Safari on Mac, only one notification can be shown at a time, even if the other notifications are not related to your site or from OneSignal. Notifications also disappear quickly within 5 seconds and this time is not customizable.

On Chrome/Firefox on Android, multiple notifications can be shown at a time.

Mobile Notification Collapsing

Anytime you want to send frequent updates to users on something that is changing, you may want to consider notification collapsing. Collapsing (removing older or irrelevant notifications) solves the problem of notifications piling up and overwhelming users whenever they are not actively checking their new notifications.

Collapsing works by only showing the latest notification of a given type, 'collapsing' all the other unread notifications of the same type that come before it. For instance, if you have a weather app and want to update users on the latest weather, you probably want to replace those notifications with whatever is the latest one.

The way notification collapsing works is by adding a collapse_id to particular types of notification you are sending that you want collapsed together (E.g. the id is weather_update). Then, every time you wish to have a future notification override previous ones, you add the same collapse id to it. If your app sends three notifications, the following would happen:

  1. Sent 1:41pm: "A storm looks like it's approaching. Better grab an umbrella!"

  2. Sent 2:20pm: "The storm in your area seems to be clearing up. Expect sunshine soon."

  3. Sent 2:44pm: "The storm has moved north and the sun will shine the rest of today!"

If a user does not open their device until 4pm, they would only see the third notification. If the user opened their device at 2pm and 4pm, they would see the first notification, and then at 4pm see the third notification.

collapse_id does not work with Data Notifications on iOS, the notification must show data in this case to remove it from view.

Notifications when app is closed

iOS devices will always receive notifications. They may be delayed, however, if the app is in Low Power Mode.


A normal close such as swiping your app away is a normal close and won't be an issue on most devices. However, force-closing it through the app settings, task killer, or through Android Studio would result in most Intents (including pushes) preventing services from starting.

Also some Xiaomi and Huawei devices will put your app in a force-closed state after swiping it away or after some time. See the following documentation for more details on this and the logcat message to confirm this.

Notification Grouping

See how each platform works:

Notification Priority

Android Notifications can be assigned normal or high priority.

For Android 7.1 and lower, priority handles both "Delivery Priority" and "Display Priority"

For Android 8+, priority handles "Delivery Priority" and Android Notification Categories handles the "Display Priority"

Normal Priority: If the app is in the foreground, normal priority notifications are delivered immediately (except in Doze mode). Choose this setting for things such as new message notifications, syncing your UI, and syncing data in the background.

High Priority: These notifications are delivered immediately, though fall subject to the standby bucket policy on the device.

  • Set a high priority 10 if you need it to go through any doze mode / other power saving modes. But only use priority 10 when you really need to as there is a daily limit where it might fallback to normal priority.


Android 8+ notifications can be assigned a category. Read our Android Notification Categories guide.

Doze Mode

Android devices have a doze mode, where messages will be delayed until the device is out of doze mode. High priority messages are delivered but will nevertheless fall subject to the standby bucket policy on the device.

App Standby Buckets

Devices running Android P and newer implement app standby buckets which may lead to notifications being delayed.

The following values may change. See the Android docs for most updated values


"Jobs" = Normal

"Alarms" = High


No restriction

No restriction

Working set:

Deferred up to 2 hours

Deferred up to 6 mins


Deferred up to 8 hours

Deferred up to 30 mins


Deferred up to 24 hours

Deferred up to 2 hours

OneSignal Custom Push Payload

Each OneSignal SDK has a Notification Event Observer that gets triggered when a push is clicked or received.

Details on the OneSignal Notification Object and OneSignal Notification Payload.

On Android, our notification payload contains a “custom” key with a nested “i” value. If the notification payload received does not contain this, our SDK will not process the notification.

On iOS, we also have the same “custom” key with nested “i” value, however because Apple has a standard payload it will show all notification sent to the device. So if you send a push from your old platform to a device, do not send the same notification from OneSignal or the user will get it twice.

For iOS Click Handlers, depending on how you handle notification opens you might have to add a check for "custom": { "i": ""} as well. Or if you have your own format, we recommend checking for yours instead.

Adding Notification Data to iOS Root Payload

If you are needing to customize iOS payload, you can set your OneSignal app to include this custom data in the payload using our Update an app method and set additional_data_is_root_payload equal to true

Then any push you send with the data or Additional Data from the dashboard will be available in the APNS payload. For example:

... OneSignal Notification Data
"data": {
   "your-custom-data": "1"

will result int he following sent to the device:

    "aps" : {
        "alert" : {
            "title" : "Notification Title",
            "body" : "Notification Body",
    "your-custom-data": "1"

Resulting in any additional code checking and handling this your-custom-data key at this location to work.

Updated 6 months ago

Notification Behavior & Payload Information

Concepts - Notification delivery and behavior

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.