Mobile Push Notifications

Overview of Push Notification Customizations.


Major Release: User Model Beta

We are in the process of migrating to a new user-centric data model. To learn more check out the User Model Beta Overview
Version 9 of our documentation is now out of date. Version 11 of our documentation has been updated for this change.


Push Notifications are Rich Text Format messages that get "pushed" from a server and are then received on displayed on your user's device, even if the app is not open.

The purpose of this guide is to give you a general overview of push notification content and best practices. If you are developing a website, we have a separate guide for Web Push Notifications.


Examples of mobile push notification layouts for iOS and Android

How push notifications work

Push notifications are banner-style messages that can contain text, images, buttons, and sometimes more functionality (depending on the device's operating system).

Devices subscribe or "opt-in" to receive push notifications, usually through a prompt on iOS mobile apps. Android mobile app subscriptions occur as soon as the device downloads and opens the app.

Design Guide

Below is a brief outline of options you can configure for your mobile push notifications in OneSignal. Each mobile operating system supports push notifications differently.

For more in-depth platform-specific details, see our Push Notification Design blog post.

Notification ContentDetails
1TitleRestricted to 50 characters.

API: headings property

Emojis πŸ‘
Message Personalization
Language & Localization
2ContentRestricted to 150 characters.

API: contents property

Emojis πŸ‘
Message Personalization
Language & Localization
3IconsAndroid provides Small and Large Icons. Both of which can be customized following Android: Notification Icons.

API: small_icon & large_icon property

iOS sets the icon based on the App's default icon.
4Large Image1440x720 or 2:1 aspect ratio. PNG, JPG, GIF (iOS only supports animated GIF Android GIF frozen on first frame).

API: ios_attachment & big_picture property
5Action ButtonsCustomizable buttons to perform a custom action.

API: buttons property
6TimestampSet by device. When the message was received.
7App NameiOS: The Display Name in Xcode.
Android: The <application android:label="YOUR APP NAME"> in the AndroidManifest.xml

Additional Content Support

Additional ContentDetails
SoundsSupported on iOS and Android mobile apps.

Android uses Android: Notification Channel Categories.

API: ios_sound & android_channel_id property
BadgesRed dots with numbers for iOS and Android mobile apps.

Android uses Android: Notification Channel Categories.

API: ios_badgeType & ios_badgeCount property

Notification Behavior & Interruption

You can also control some aspects of the Notification's Behavior & Payload, such as how long the push will be held by FCM/APNS when the device is offline, collapsing notifications, and more.

Deep-links and URLsWhen clicked, sends subscribers to a custom URL or view within the app.

API: url property
Pop-up display and InterruptionAndroid: Notification Channel Categories sets the Importance of the notification to display as a "heads up" or "banner" type or go straight to Notification Center.

iOS: Focus Modes and Interruption Levels sets the Interruption level of the notification to display as a "heads up" or "banner" type or go straight to Notification Center.
Time To LiveHow long the push is saved on the FCM/APNS/WNS servers if the subscriber's device is offline.

API: ttl property
Collapse IdReplaces Notifications already present on the subscriber's device if the current notification contains the same collapse_id.

API: collapse_id property
Background and Data NotificationsSending notifications without a visual appearance to the subscriber. Mobile only.
Additional DataAdditional content that is not visible may accompany a message payload. See below FAQ for "How much data can a push notification hold?".

API: data property

Character Limits

Because each platform uses a different visual layout for messages, the amount of content that is visible in a notification can vary. The following are approximations for how many characters in a notification based on platform.

Emojis count as a single character.

iOS~25-50 (same for Subtitle)~150
Best Fit Across All Platforms
(Including Web)


You can copy and paste emojis directly into the Title, Subtitle, and Message of the notification. Any standard emoji will work, and you can use for more.


Emoji Limitations

Emojis are controlled by the operating system that is receiving the notification, and the operating system must support emoji for the emoji characters to be seen.


How much data can a push notification hold?

Push notification payloads cannot exceed 4096 bytes of data.
Push notification additional data cannot exceed 2048 bytes of the 4096 bytes allowed.
Each platform has different data limits. The total character limit is based on the body, title, and any images or custom data you add. Generally, the limit can be 3500 characters.