Data & background notifications

Send silent push notifications to sync data or trigger background tasks on iOS and Android without displaying a visible message.

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: OneSignal only sends data notifications to subscribed Subscriptions. To reach unsubscribed users, see this iOS SDK 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, 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:

• Pushing Background Updates to Your App
• Generating a Remote Notification

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:

• FCM data messages
• Optimize for Doze and App Standby

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.

---

Huawei (HMS) data notification setup

On Huawei devices, OneSignal chooses how to deliver each push to HMS using the huawei_msg_type API parameter:

• data: HMS delivers the payload to the device and the OneSignal SDK processes it client-side. This is the type you need for silent notifications on Huawei, and it’s also what the SDK uses to render visible full-featured notifications (images, buttons, confirmed delivery).
• message: HMS Core handles the notification server-side and displays a title and body only. Use data if you need silent delivery or background processing.

huawei_msg_type=data is not the same as a silent notification. It’s the HMS transport type. A data-type push that includes visible content (contents/headings) still displays a full notification. The SDK renders it locally. To send a silent push on Huawei, use huawei_msg_type=data and omit visible content (follow the steps above).

As with Android, if the app has been force-stopped, HMS Core will not start it to process the notification, so a data-type push won’t be delivered. 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

Do confirmed deliveries work with silent notifications?

Android: Yes, if the app has not been force-stopped. See Android force-stop behavior.

iOS: 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 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.

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

No. Silent notifications are best-effort, so they can be delayed or dropped, and they don’t trigger confirmed delivery callbacks, so you have no reliable way to know which users received the push. See Limitations for details.

To measure reachable users, send a visible notification and track delivery metrics in Analytics.

---

Related pages

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.