OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Push Notification Guide

Overview of Push Notification Customizations.

Push Notifications are "Rich Text" Format messages that get "pushed" from the FCM/APNS/WNS servers to your subscribers. Devices subscribe or "opt-in" to receive push notifications usually through Prompting like on Web Browsers or iOS Mobile Apps, but Android Mobile App subscriptions occur as soon as the device downloads and opens the app. Checkout Apple's WWDC 2020 Push Notifications Primer for more details.

Once a device is subscribed, you can start Sending Push Messages.

The layout of push notifications is controlled by the Platform (Chrome vs Firefox vs Android vs iOS) and Operating System (MacOS, Windows, Linux) so you are not able to move the elements of the push, but you can set the following Content.

Notification ContentDetails
Character LimitsHow many characters are allowed and recommended per platform.
Emoji support is available across all platforms 👍
ImagesLarge Images that appear with the notification. Supported by iOS, Android and Chrome on Windows/Android.
IconsSupported on all platforms.
SoundsSupported on iOS and Android mobile apps. Not customizable on Web Push.
BadgesRed dots with numbers for iOS and Android mobile apps. Web Push badges are the small icons on Chrome for Android.
Action ButtonsCustom buttons that can support different actions or links.

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

Notification BehaviorDetails
Deep-links and URLsWhen click, send users to a custom url or view within the app.
Time To LiveHow long the push is saved on the FCM/APNS/WNS servers if the user's device is offline.
Collapse IdReplaces Notifications already present on the user's device if current notification contains this same collapse_id.
Notification PersistenceOnly available on certain platform versions.
Background and Data NotificationsSending notifications without a visual appearance to the user. Mobile only.
Additional DataCustom data sent within a push.


Because each platform uses a different visual layout for messages, the amount of content that is visible varies. A rough approximation for what is visible on a platform can be seen in notification previews in New Message.

Character limits

The following are approximations for how many characters in a notification based on platform.

Emojis count as a single character. Simply copy-paste the emoji you want into the message or title. Some limitations on Windows 7 and older Operating Systems.

iOS~25-50 (same for Subtitle)~150
Web Push (Windows): Chrome~60 (Chrome 68+)
~40 (Chrome 67 and lower)
~120 (Chrome 68+)
~0 - 150 (Chrome 67 and lower)
Web Push (Windows): Firefox~40~140-190
Web Push (Mac): Chrome, Firefox, Safari~20-40~20-80
(to fit across all platforms)

Web Push Character Limits


Chrome 68+ do not have any restrictions with images added and show about the same title (~60 characters on screen and ~60-80 in Notification Center) and body (~126 characters on screen and ~120-160) count.


Titles support ~40 characters, and bodies support ~140-190 characters:


All Mac browsers (except Safari) have the same limits due to the way MacOS treats notifications. The features a notification is sent with (such as Icons and the SDK-only persistNotification) affect the amount of characters visible:

With Icon~32~35
With persistNotification~30~33
With persistNotification + Icon~21~24
Notification Center Default~39~80
Notification Center + Icon~30~62

There is not a way to remove or edit the site icon on Safari without changing the default icon set in your OneSignal Dashboard.



Exact character limits depend on which characters are used

Note that the width of individual characters also affects the amount of content visible, such as in this Chrome on Windows example:

Additional data

Additional content that is not visible may accompany a message payload. Each platform has different limits this, and is based on the body, title, and any images or custom data you add. This is roughly 3500 characters for both Android and iOS.


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 must support the emoji for it to be seen.


Adding large images to notifications can be done across iOS and Android Mobile Apps and Chrome Browsers on Windows and Android. Firefox, Safari and Edge do not support big images. Chrome 59+ on MacOS stopped supporting large images. You can find more details about this change in our blog post.

You can add images to these platforms using:

  1. The Dashboard Global Image Field
  2. The API Image Parameters (Global Image not supported on API)
  3. WordPress Users: Add Images directly through the Plugin. See Add Featured Image to Notification

Recommended Image Details

Web PushAndroidiOS
Filetypespng, jpg, gif*jpg, jpeg, png, gif*jpg, jpeg, png, gif
ResolutionChrome (Windows only): 360x180 or 2:1 aspect ratio

Chrome on Android: 1024x512 or 2:1 aspect ratio
1440x720 or 2:1 aspect ratio1024x1024 or 1:1 aspect ratio
DocumentationWeb Push Image GuideAndroid Big Picture GuideiOS Rich Media Guide
OneSignal API Parameterchrome_web_imagebig_pictureios_attachments
  • gif image animations not supported on Web Browsers or Android mobile apps.
  • Adding Action Buttons may affect image sizes, please try testing on your devices to make sure the layout fits your needs.
  • Chrome 56+ on macOS does not support images.
  • For troubleshooting, see Notification Images Not Showing


Notification icons are usually added upon Website or Mobile App setup. Web Push and Android Mobile App Large icons can use external resource urls or you can upload the image directly to OneSignal for us to host it. Details on adding these in our API Icon Parameters or through our Dashboard Notification Creation

Our API does not contain a Global Icon Field like our Dashboard Global Image Field but the chrome_web_icon parameter will work for Firefox and Edge. Safari does not allow custom icons. See Safari Web Push Setup to add the Safari Icon.

Web PushAndroidiOS
DocumentationWeb Push Notification Icons GuideAndroid Notification Icons GuideUses the app's default icon.


OneSignal supports adding custom sounds for any notification sent. To learn more, read our guide on Customizing Notification Sounds.


Android & iOS - See the Badges Guide

Web Push badges are the small icon you see on the notification. More details in Web Push Notification Icons

Action Buttons

OneSignal supports action buttons on all platforms. See our Action Buttons documentation for more details.

Notification Persistence

Most platforms and operating systems support a Notification Center where notifications will persist until user interaction.

For Web Push, Chrome allows notification persistence (stay on screen) for certain operating systems versions with additional setup. See our Notification Persistence Guide for more details.

Updated 15 days ago

Push Notification Guide

Overview of Push Notification Customizations.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.