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 NotificationExtenderService.
iOS background notification setup
Before configuring background pushes on iOS, review:
Enable remote notifications capability
This is typically included if you followed our Mobile SDK Setup.
Format the payload
To send a silent background notification:
Omit contents in your Create notification API request.
- If sending via Dashboard: Leave the “Message” field empty.
Set content_available to true.
- If using Dashboard: Toggle Platform Settings > Send to Apple iOS > “Content available”.
Add custom payload with the data field.
- Dashboard path: Advanced Settings > Additional Data.
Handle the data
Use the AppDelegate method application(_:didReceiveRemoteNotification:fetchCompletionHandler:) to process the notification.
⚠️ Important
Background notifications cannot be processed if the app has been swiped away.
In such cases, include a visiblecontentsmessage and process data in theUNNotificationServiceExtension.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.
Conditions for silent notification via REST API
OneSignal will treat a message as a background/data notification when all of the following are true:
"content_available": truealert,badge,sound,category,thread_id,subtitle,contents, andheadingsare omitted
Sending VoIP notifications
VoIP notifications are supported for iOS but require additional setup outside of the OneSignal SDKs, which do not register for VoIP tokens.
See the VoIP Notifications Setup Guide for full instructions.
FAQ
Can silent background notifications detect uninstalls or unsubscribes?
Can silent background 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.
Do confirmed deliveries work with silent notifications?
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.