Overview
Silent notifications let you wake your app and perform background tasks—such as syncing or refreshing data—without showing a visible message or playing a sound. On iOS, these are called Background Notifications, and on Android, they’re known as Data Notifications. Together, they’re often referred to as silent pushes and behave differently from normal, visible notifications. This guide explains how to configure and send silent notifications with OneSignal across supported platforms.Limitations
Silent notifications behave differently from normal push messages and have several platform-specific limitations.- Apps cannot receive silent pushes if:
- iOS: The app has been closed by the user like when swiped away from the app switcher. (See Apple support).
- Android: The app has been force-quit via device settings or automatically by some manufacturers when swiped away. (More details here).
- Delivery is not guaranteed:
- Both Apple and Google treat silent notifications as best-effort. iOS may delay or drop delivery under Low Power Mode, Background App Refresh off, or if the app was closed by the user. Android may throttle or batch delivery under Doze or OEM power-saving rules.
- Because of this, silent notifications should never be used for critical updates.
- Subscribed users only: The OneSignal SDK only sends data notifications to subscribed Subscriptions. To reach unsubscribed users, follow this workaround.
- Limited support for cross-platform 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.
Sending silent notifications from OneSignal
Follow these steps to send a silent notification from OneSignal:1
Omit visible content
Remove any visible text or titles from the message. This includes:
- API:
contents,headings,subtitlein your Create notification API request. - Dashboard: Message, Title, Subtitle
2
Set content_available
- API: Set
content_availabletotrue. - 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 data to the notification
- API: Use the
dataparameter. - Dashboard: Use the Additional Data fields.
Platform-specific setup
iOS background notification setup
To handle background notifications, your iOS app must have the Background Modes > Remote Notifications capability enabled in Xcode. This is typically added if you followed our Mobile SDK Setup. Apple documentation:- Pushing Background Updates to Your App
- Generating a Remote Notification
- To process the notification, use the
AppDelegatemethodapplication(_:didReceiveRemoteNotification:fetchCompletionHandler:).
Android data notification setup
Handle data notifications on Android using the Notification Service Extension. This lets you:- Process notifications as long as the app hasn’t been force closed
- Customize how notifications are displayed or suppressed
Sending VoIP notifications
VoIP notifications are supported but require additional configuration outside the standard OneSignal SDKs. OneSignal does not register VoIP tokens automatically. For setup instructions, see the VoIP Notifications Setup Guide.FAQ
Can silent notifications be used to detect uninstalls or unsubscribes?
Technically yes, but it’s unreliable. As explained in the Limitations section above, silent notifications are not guaranteed to be delivered. Instead:- Send visible notifications (with content) to all your users at least once a month.
- Optionally send silent notifications as a supplemental check.