​

Overview

Background or data notifications—often called “silent” notifications—do not display a message or play a sound. Instead, they are designed to silently wake your app to perform background tasks such as syncing or refreshing data.

​

Limitations

• Subscribed users only: The OneSignal SDK sends data notifications only to subscribed users by default. To reach unsubscribed users, follow this workaround.
• Force-closed apps can’t receive background pushes:
  • iOS: Apps are force-closed when swiped away from the app switcher. Apple support.
  • Android: Apps may be force-closed via device settings or automatically by some manufacturers when swiped away. More info.
• Limited support for non-native 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 NotificationExtenderService.

​

iOS background notification setup

Before configuring background pushes on iOS, review:

• Pushing Background Updates to Your App
• Creating Notification Payloads

​

Enable remote notifications capability

This is typically included if you followed our Mobile SDK Setup.

​

Format the payload

To send a silent background notification:

​

Handle the data

Use the AppDelegate method application(_:didReceiveRemoteNotification:fetchCompletionHandler:) to process the notification.

⚠️ Important
Background notifications cannot be processed if the app has been swiped away.
In such cases, include a visible contents message and process data in the UNNotificationServiceExtension.didReceive.

There is no way to process a background notification if the app has been force-closed.

​

Android data notification setup

Use the NotificationExtenderService to handle data notifications on Android.

This enables:

• Handling background notifications when the app is not running.
• Customizing how notifications are displayed or suppressed.

​

Conditions for silent notification via REST API

OneSignal will treat a message as a background/data notification when all of the following are true:

• "content_available": true
• alert, badge, sound, category, thread_id, subtitle, contents, and headings are omitted

​

Sending VoIP notifications

VoIP notifications are supported for iOS but require additional setup outside of the OneSignal SDKs, which do not register for VoIP tokens.

See the VoIP Notifications Setup Guide for full instructions.

​

FAQ