> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://support.apple.com/en-us/HT201330)).
  * **Android**: The app has been force-quit via device settings or automatically by some manufacturers when swiped away. ([Android force-stop behavior](./notifications-show-successful-but-are-not-being-shown#android-app-is-force-stopped)).
* **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](./subscriptions). To reach unsubscribed users, see [this iOS SDK workaround](https://github.com/OneSignal/OneSignal-iOS-SDK/issues/302).
* **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:`](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623013-application).
  * Android requires implementation of a [Notification Service Extension](./service-extensions).

***

## Sending silent notifications from OneSignal

Follow these steps to send a silent notification from OneSignal:

<Steps>
  <Step title="Omit visible content">
    Remove any visible text or titles from the message. This includes:

    * **API**: `contents`, `headings`, `subtitle` in your [Create notification](/reference/create-message) API request.
    * **Dashboard**: Message, Title, Subtitle
  </Step>

  <Step title="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.
  </Step>

  <Step title="Add data to the notification">
    * **API**: Use the `data` parameter.
    * **Dashboard**: Use the **Additional Data** fields.
  </Step>
</Steps>

### Example API payload

```bash theme={null}
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](./mobile-sdk-setup).

To process the notification, implement the `AppDelegate` method [`application(_:didReceiveRemoteNotification:fetchCompletionHandler:)`](https://developer.apple.com/documentation/uikit/uiapplicationdelegate/1623013-application).

Apple documentation:

* [Pushing Background Updates to Your App](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/pushing_background_updates_to_your_app?language=objc)
* [Generating a Remote Notification](https://developer.apple.com/documentation/usernotifications/generating-a-remote-notification)

<Warning>
  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`](./service-extensions#ios-notification-service-extension).
</Warning>

***

### Android data notification setup

Handle data notifications on Android using the [Notification Service Extension](./service-extensions).

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](https://firebase.google.com/docs/cloud-messaging/concept-options#data_messages)
* [Optimize for Doze and App Standby](https://developer.android.com/training/monitoring-device-state/doze-standby)

<Warning>
  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](./notifications-show-successful-but-are-not-being-shown#android-app-is-force-stopped).
</Warning>

***

## Sending VoIP notifications

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

<Card title="VoIP Notifications Setup Guide" icon="phone" href="./voip-notifications">
  Configure VoIP push notifications for real-time calling on iOS.
</Card>

***

## 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](#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](./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](./analytics-overview).

***

<Columns cols={2}>
  <Card title="Service extensions" icon="puzzle-piece" href="./service-extensions">
    Handle notification processing in native code on iOS and Android.
  </Card>

  <Card title="Subscriptions" icon="address-book" href="./subscriptions">
    Understand Subscription types and how they connect to Users.
  </Card>

  <Card title="Create Message API" icon="code" href="/reference/create-message">
    Send notifications programmatically, including silent pushes.
  </Card>
</Columns>