> ## 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.
# OSNotification payload
> Reference for OneSignal's OSNotification object, including all payload fields, Android and iOS-specific properties, custom data, and click actions.
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**: Use the [notification lifecycle listener](./mobile-sdk-reference#addforegroundlifecyclelistener-push)
* **iOS**: Use the [notification lifecycle listener](./mobile-sdk-reference#addforegroundlifecyclelistener-push) or a `UNNotificationServiceExtension`
### Android fields
| Property | Type | Description |
| ---------------------------- | :---------------------: | -------------------------------------------------------------------- |
| `getBody()` | `String` | Body text of the notification. |
| `getTitle()` | `String` | Title of the notification. |
| `getLaunchURL()` | `String` | URL opened when the notification is clicked. |
| `getNotificationId()` | `String` | OneSignal notification UUID. |
| `getAdditionalData()` | `JSONObject` | Custom key-value data set via dashboard or REST API. Max 2048 bytes. |
| `getTemplateId()` | `String` | Template UUID, if sent using templates. |
| `getAndroidNotificationId()` | `int` | Android native notification ID. |
| `getLargeIcon()` | `String` | URL or resource name of large icon. |
| `getSmallIcon()` | `String` | Small icon resource name. |
| `getSmallIconAccentColor()` | `String` | Icon accent color in ARGB format. |
| `getSound()` | `String` | Sound resource name played. |
| `getCollapseId()` | `String` | Collapse key for notification replacement. |
| `getPriority()` | `int` | Android priority (-2 to 2). |
| `getLedColor()` | `String` | LED color in ARGB format. |
| `getLockScreenVisibility()` | `int` | Lock screen visibility: `1 = public`, `0 = private`, `-1 = secret`. |
| `getFromProjectNumber()` | `String` | Sender project number. |
| `getGroupedNotifications()` | `List` | Notifications included in a summary. |
| `getGroupKey()` | `String` | Group key used in summaries. |
| `getGroupMessage()` | `String` | Summary text. |
| `getBackgroundImageLayout()` | `BackgroundImageLayout` | Object for background image layout and text colors. |
| `getActionButtons()` | `List` | Action buttons with icon, text, and ID. |
| `getRawPayload()` | `String` | Full raw JSON string of the payload. |
### iOS fields
| Property | Type | Description |
| ------------------ | :------------: | ---------------------------------------------------------------------------- |
| `body` | `NSString` | Body text of the notification. |
| `title` | `NSString` | Title of the notification. |
| `launchURL` | `NSString` | URL opened when the notification is clicked. |
| `notificationId` | `NSString` | OneSignal notification UUID. |
| `additionalData` | `Dictionary` | Custom key-value `data` set via dashboard or REST API. Max 2048 bytes. |
| `templateId` | `NSString` | Template UUID, if sent using templates. |
| `subtitle` | `NSString` | Subtitle text. |
| `category` | `NSString` | iOS category identifier. |
| `threadId` | `NSString` | Used to group notifications into threads (iOS 10+). |
| `badge` | `NSInteger` | Absolute badge value. |
| `badgeIncrement` | `NSInteger` | Amount to increment the badge. |
| `contentAvailable` | `BOOL` | If `content-available=1`, triggers background fetch. |
| `mutableContent` | `BOOL` | If `mutable-content=1`, triggers a Notification Service Extension. |
| `actionButtons` | `NSArray` | iOS action buttons. |
| `rawPayload` | `NSDictionary` | Full raw JSON of the payload. |
| `parseWithApns` | *Method* | Converts raw APNs payload into an OSNotification. Use in service extensions. |
***
## `OSNotificationAction` (click events)
Describes the user's interaction with the notification.
| Property | Type | Description |
| ---------- | :------: | ----------------------------------------------------- |
| `actionId` | `String` | The ID of the clicked action button. |
| `type` | `enum` | `Opened` (default tap) or `ActionTaken` (button tap). |
***
## Custom OneSignal payload structure
All OneSignal notifications include a special `"custom"` object in the payload:
```json theme={null}
{
"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](./migrating-to-onesignal#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](/reference/update-an-app) and set:
```json theme={null}
{
"additional_data_is_root_payload": true
}
```
**2. Send a push with `data`**
The `data` fields appear in the APNs root payload:
```json theme={null}
{
"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.
| Property | Type | Description |
| ----------- | :-------: | ----------------------------------------------------------------- |
| `restoring` | `boolean` | `true` 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](/reference/update-an-app) to place `additionalData` fields in the APNs root instead of inside the `custom` dictionary. See [Move additionalData to APNs root](#move-additionaldata-to-apns-root) for details.
***
Configure notification channels for Android 8.0+ devices.
Add rich media, badges, and confirmed receipt tracking.
Full reference for OneSignal's mobile SDK methods and listeners.