Remove Notifications and TTL

How to remove notifications from a user's device.

Notification Collapsing

If sending frequent notifications, especially on something that is changing like "breaking news", you may want to consider notification collapsing. Collapsing is replacing older or irrelevant notifications with newer ones; solving the problem of notifications piling up and overwhelming users whenever they are not actively checking their new notifications.

Mobile Notification Collapsing - Collapse ID

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 notifications you are sending that you want collapsed together (E.g. the id is weather_update or breaking news). 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.

Web Notification Collapsing - Web Push Topic

See Web Push Topic & Collapsing.

Removing Notifications Without Replacing Them

In some cases, you may want notifications to "self-destruct" or be removed from the device without replacing them with others. There are a couple options for this:

Android: Within the Notification Service Extension, use the native Android API setTimeoutAfter method to remove the notification after a certain amount of time.

iOS: Apple provides the native removeDeliveredNotifications(withIdentifiers:) method and getDeliveredNotifications(completionHandler:) method to target the expired notifications and remove them.

Android & iOS: You can send Data & Background Notifications which do not display any content to the user but can remove notifications.

  • Android: run code in Service Extensions to remove the notification.
  • iOS: the notifications in the Notification Center are tied to the Badge Count. As long as you have at least 1 badge set, you can send a notification setting the badge count to 0 to remove all notifications for your app.

Web: There is not a way to remove web push notifications without collapsing.


Time To Live

This is the amount of time a notification will be held by the Google (FCM), Apple (APNs), Huawei (HMS) servers if the subscriber's device does not have an internet connection. By default, OneSignal sets this to 3 days. This means if the device does not connect to the internet within 3 days, the message will not be sent to that device. The maximum amount of time is 2,419,200 seconds or 28 days.

If the TTL value is 0, APNs/FMC treats the notification as if it expires immediately and does not store the notification or attempt to redeliver it if the device is not connected to a network. HMS requires a minimum value of 1.

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.

Time to Live can be set within the dashboard when Sending Push Messages or using the API ttl property.

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.