Data & background notifications

Learn how to configure and send silent background and VoIP notifications with OneSignal across iOS, Android, and supported derivatives. Includes payload setup, SDK requirements, and platform-specific limitations.

Overview

Background or data notifications—often called “silent” notifications—do not display a message or play a sound. Instead, they are designed to silently wake your app to perform background tasks such as syncing or refreshing data.

Limitations

• Subscribed users only: The OneSignal SDK sends data notifications only to subscribed users by default. To reach unsubscribed users, follow this workaround.
• Force-closed apps can’t receive background pushes:
  • iOS: Apps are force-closed when swiped away from the app switcher. Apple support.
  • Android: Apps may be force-closed via device settings or automatically by some manufacturers when swiped away. More info.
• Limited support for non-native SDKs:
  • Silent notifications must be handled in native code (Java/Kotlin for Android, Swift/Obj-C for iOS).
  • iOS requires implementation of application:didReceiveRemoteNotification:fetchCompletionHandler:.
  • Android requires implementation of a Notification Service Extension.

---

Setup background data notifications

To send a silent background data notification from OneSignal, follow these steps:

1. Omit contents

   Remove visible contents from the message. This includes:

   • API: contents, headings, subtitle in your Create notification API request.
   • Dashboard: Message, Title, Subtitle
2. Set content_available

   • API: Set content_available to true.
   • Dashboard: Check Content available under “Send to Apple iOS”. This is applicable for all platforms and just tells our system that no message is being sent.
3. Add custom payload

   • API: Add custom payload with the data field.
   • Dashboard: Add custom payload with the Additional Data field.

---

iOS background notification setup

Your iOS app must have the Background Modes > Remote Notifications capability enabled in Xcode. This is typically included if you followed our Mobile SDK Setup.

We also recommend reviewing the following Apple documentation:

• Pushing Background Updates to Your App
• Creating Notification Payloads

Handle the data

Use the AppDelegate method application(_:didReceiveRemoteNotification:fetchCompletionHandler:) to process the notification.

Background notifications cannot be processed if the app has been swiped away.

In such cases, include a visible contents message and process data in the UNNotificationServiceExtension.didReceive.

There is no way to process a background notification if the app has been force-closed.

---

Android data notification setup

Use the NotificationExtenderService to handle data notifications on Android.

This enables:

• Handling background notifications when the app is not running.
• Customizing how notifications are displayed or suppressed.

---

Sending VoIP notifications

VoIP notifications are supported but require additional setup outside of the OneSignal SDKs, which does not register for VoIP tokens on iOS.

See the VoIP Notifications Setup Guide for full instructions.

---

FAQ

Can silent background data notifications detect uninstalls or unsubscribes?

No. Apple and Google intentionally prevent sending silent notifications from being used as a way to detect uninstalls by not consistently responding that a device has unregistered from push, among other technical means.

The app cannot be force-closed to receive background data notifications (see Limitations).

Do confirmed deliveries work with silent notifications?

iOS: No. Confirmed delivery relies on the NotificationServiceExtension (NSE), which only activates when a visible message (contents) is included. Even if you attempt to blank out the message body in the NSE, iOS will restore the original body content—making the notification visible. Therefore, confirmed delivery does not work with silent notifications.

Android: Yes.

---