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
• iOS: Use the notification lifecycle listener 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<OSNotification>	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<ActionButton>	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:

{
  "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.

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 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 receipt tracking.

Mobile SDK reference

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