Skip to main content

​
What are silent notifications?

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.

​
Limitations

  • Apps cannot receive silent pushes if:
    • iOS: The app has been closed by the user, such as swiping it 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. (Android force-stop behavior).
  • 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, see this iOS SDK workaround.
  • Limited support for cross-platform SDKs:

​
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, 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”. Despite the label, this setting applies to all platforms and signals to OneSignal that no visible message is included.
3

Add data to the notification

  • API: Use the data parameter.
  • Dashboard: Use the Additional Data fields.

​
Example API payload

curl -X POST https://api.onesignal.com/notifications \
  -H "Authorization: Key YOUR_APP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "YOUR_APP_ID",
    "include_aliases": { "external_id": ["user-123"] },
    "target_channel": "push",
    "content_available": true,
    "data": {
      "action": "sync_data",
      "version": "2"
    }
  }'

​
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 the Mobile SDK Setup. To process the notification, implement the AppDelegate method application(_:didReceiveRemoteNotification:fetchCompletionHandler:). Apple documentation:
If the user has closed the app (swiped it away from the app switcher), iOS will not deliver the notification.In such cases, include a visible contents message and process data in the UNNotificationServiceExtension.didReceive.

​
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
Android documentation:
If the app has been force-stopped (via device settings or by some OEM battery optimization), Android will not deliver the notification. See Android force-stop behavior.

​
Sending VoIP notifications

VoIP notifications are supported but require additional configuration outside the standard OneSignal SDKs. OneSignal does not register VoIP tokens automatically.

VoIP Notifications Setup Guide

Configure VoIP push notifications for real-time calling on iOS.

​
FAQ

​
Can silent notifications be used to detect uninstalls or unsubscribes?

Not reliably. Silent notifications are best-effort and not guaranteed to be delivered, as explained in the Limitations section. Instead:
  • Send visible notifications (with content) to all your users at least once a month.
  • Optionally send silent notifications as a supplemental check.
For more details on handling subscription status changes, see the Subscriptions guide.

​
Do confirmed deliveries work with silent notifications?

No. Confirmed deliveries require the SDK to execute a callback when the notification is displayed. Silent notifications are not displayed, so the SDK receipt callback is never triggered.

​
Can I use silent notifications to measure how many users are reachable?

No, not reliably. Silent notifications aren’t guaranteed delivery.
  1. Delivery is not guaranteed — both Apple and Google treat silent notifications as best-effort and may delay or drop them. For example, iOS will drop them if the app is closed (force quit) and Android and iOS will throttle them under power-saving rules.
  2. Delivery is not confirmed — confirmed deliveries do not work with silent notifications, so you have no way to know which users actually received the push.
To measure reachable users, send a visible notification and track delivery metrics in Analytics.

Service extensions

Handle notification processing in native code on iOS and Android.

Subscriptions

Understand Subscription types and how they connect to Users.

Create Message API

Send notifications programmatically, including silent pushes.