> ## 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**: OneSignal 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>

***

### Huawei (HMS) data notification setup

On Huawei devices, OneSignal chooses how to deliver each push to HMS using the [`huawei_msg_type`](/reference/push-notification#body-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.

<Warning>
  `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](#sending-silent-notifications-from-onesignal)).
</Warning>

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

***

## 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

### Do confirmed deliveries work with silent notifications?

**Android**: Yes, if the app has not been force-stopped. See [Android force-stop behavior](./notifications-show-successful-but-are-not-being-shown#android-issues).

**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](#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.

### 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](#limitations) for details.

To measure reachable users, send a visible notification and track delivery metrics in [Analytics](./analytics-overview).

***

## Related pages

<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>