Skip to main content
The OSNotification class represents the push notification payload in OneSignal’s SDKs. Use it to access notification title, body, custom data, and platform-specific properties when handling notifications in your app.
Push notification payloads are limited to 4096 bytes. To avoid truncation, keep payloads under 3500 bytes. The additionalData field is limited to 2048 bytes.

​
Accessing OSNotification in your app

All OneSignal SDKs provide a notification event listener that returns an OSNotification object:

​
Android fields

PropertyTypeDescription
getBody()StringBody text of the notification.
getTitle()StringTitle of the notification.
getLaunchURL()StringURL opened when the notification is clicked.
getNotificationId()StringOneSignal notification UUID.
getAdditionalData()JSONObjectCustom key-value data set via dashboard or REST API. Max 2048 bytes.
getTemplateId()StringTemplate UUID, if sent using templates.
getAndroidNotificationId()intAndroid native notification ID.
getLargeIcon()StringURL or resource name of large icon.
getSmallIcon()StringSmall icon resource name.
getSmallIconAccentColor()StringIcon accent color in ARGB format.
getSound()StringSound resource name played.
getCollapseId()StringCollapse key for notification replacement.
getPriority()intAndroid priority (-2 to 2).
getLedColor()StringLED color in ARGB format.
getLockScreenVisibility()intLock screen visibility: 1 = public, 0 = private, -1 = secret.
getFromProjectNumber()StringSender project number.
getGroupedNotifications()List<OSNotification>Notifications included in a summary.
getGroupKey()StringGroup key used in summaries.
getGroupMessage()StringSummary text.
getBackgroundImageLayout()BackgroundImageLayoutObject for background image layout and text colors.
getActionButtons()List<ActionButton>Action buttons with icon, text, and ID.
getRawPayload()StringFull raw JSON string of the payload.

​
iOS fields

PropertyTypeDescription
bodyNSStringBody text of the notification.
titleNSStringTitle of the notification.
launchURLNSStringURL opened when the notification is clicked.
notificationIdNSStringOneSignal notification UUID.
additionalDataDictionaryCustom key-value data set via dashboard or REST API. Max 2048 bytes.
templateIdNSStringTemplate UUID, if sent using templates.
subtitleNSStringSubtitle text.
categoryNSStringiOS category identifier.
threadIdNSStringUsed to group notifications into threads (iOS 10+).
badgeNSIntegerAbsolute badge value.
badgeIncrementNSIntegerAmount to increment the badge.
contentAvailableBOOLIf content-available=1, triggers background fetch.
mutableContentBOOLIf mutable-content=1, triggers a Notification Service Extension.
actionButtonsNSArrayiOS action buttons.
rawPayloadNSDictionaryFull raw JSON of the payload.
parseWithApnsMethodConverts raw APNS payload into an OSNotification. Use in service extensions.

​
OSNotificationAction (click events)

Describes the user’s interaction with the notification.
PropertyTypeDescription
actionIdStringThe ID of the clicked action button.
typeenumOpened (default tap) or ActionTaken (button tap).

​
Custom OneSignal payload structure

All OneSignal notifications include a special "custom" object in the payload: 
{
  "custom": {
    "i": "the-notification-id"
  }
}
This key is required for OneSignal SDKs to process the notification. If missing, notifications will not trigger click events or analytics. If you send pushes from another service to devices that also use OneSignal, filter by this key to prevent duplicate processing. See Push payload handling for guidance.

​
Move additionalData to APNS root

For iOS apps, you can place additionalData fields in the root of the APNS payload instead of inside the custom dictionary. This simplifies access in custom notification handlers. 1. Enable via the API Use the Update an app API and set: 
{
  "additional_data_is_root_payload": true
}
2. Send a push with data The data fields appear in the APNS root payload: 
{
  "aps": {
    "alert": { "title": "Sale", "body": "20% off all items!" }
  },
  "promo_code": "SPRING20"
}
You can now access promo_code directly without checking the custom dictionary.

​
Restored notifications (Android)

The Android SDK restores notifications after a device reboot or app restart.
PropertyTypeDescription
restoringbooleantrue if the notification was restored after device/app restart.
Check the restoring flag to skip restored notifications. To prevent old notifications from restoring entirely, set a short or 0 TTL (time-to-live) when sending.

​
Push token formats

  • iOS Push (APNS): 64 characters, hexadecimal only (0-9, a-f). deviceToken.map {String(format: "%02x", $0)}.joined()
  • Android Push (FCM): Typically 163 characters, alphanumeric, may contain hyphens, colons, and underscores.

​
FAQ

​
What is the maximum payload size?

Push notification payloads are limited to 4096 bytes total. The additionalData field is limited to 2048 bytes. To avoid truncation, keep your total payload under 3500 bytes.

​
How do I identify a OneSignal notification in the raw payload?

All OneSignal notifications include a "custom" object with an "i" key containing the notification ID. Check for this key to distinguish OneSignal notifications from those sent by other providers.

​
Can I access additionalData in the APNS root payload?

Yes. Enable additional_data_is_root_payload via the Update an app API to place additionalData fields in the APNS root instead of inside the custom dictionary. See Move additionalData to APNS root for details.

Android notification categories

Configure notification channels for Android 8.0+ devices.

Mobile Service Extensions

Add rich media, badges, and confirmed delivery tracking.

Mobile SDK reference

Full reference for OneSignal’s mobile SDK methods and listeners.