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. Android Mobile App subscriptions occur as soon as the device downloads and opens the app.


Here are common layout guides to follow for push notifications across all platforms:

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 PersistenceRequiring Web Push Notifications to be interacted with to be removed. Only 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.

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
Windows: Chrome~60 (Chrome 68+)
~40 (Chrome 67 and lower)
~120 (Chrome 68+)
~0 - 150 (Chrome 67 and lower)
Windows: Firefox~40~140-190
Mac: Chrome, Firefox, Safari~20-40~20-80
Best Fit Across All Platforms~20~60

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.


Additional data

Additional content that is not visible may accompany a message payload. Each platform has different limits 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 http://getemoji.com/ 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.

App Name or Site URL

The App Name shown on the push can be changed in the following settings. Websites cannot change the Site URL shown on the push, it must always show the site origin the user subscribed to.

App NameiOSChange Display Name set in Xcode.
App NameAndroidChange the <application android:label="YOUR APP NAME"> in the AndroidManifest.xml
Site URLWebSite Origin User Subscribed. Cannot be changed.


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.

Recommended Image Details

Web PushAndroidiOS
Filetypespng, jpg, webp, gif*jpg, jpeg, png, gif*jpg, jpeg, png, gif
ResolutionRecommendations: 2:1 aspect ratio landscape

Max Width: 2000 pixels
Min Width: 300 pixels

Common sizes:
Recommendations: 2:1 aspect ratio landscape

Max Width: 2000 pixels
Min Width: 300 pixels

Common sizes:
Recommendations: 2:1 aspect ratio landscape

Max Width: 2000 pixels
Min Width: 300 pixels

Common sizes:
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


All Push Notifications support some type of icon.

Web Push Icons can be set within your OneSignal Dashboard Settings. Some browsers like Chrome, Firefox and Edge allow you to send notifications with different icons. Safari does not allow custom icons. See Safari Web Push Setup to add the Safari Icon.

Mobile Push Icons are set within your mobile app. Android Mobile App Large icons can use external resource. iOS only uses the main app icon.

Web PushAndroidiOS
Sending Push MessagesWeb Push Notification Icons GuideAndroid Notification Icons GuideUses the app's default icon.
API Icon Parameterschrome_web_icon works for Chrome, Firefox and Edge. Safari does not support custom icons.large_iconUses 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.

Notification Behavior

Learn about how to setup Notification Collapsing, Time to live and understand common Notification Behavior & Payload Information.


Can OneSignal send Push Notifications in an On-Premise Closed network?

This can work as long as the computers on your closed network have access to the push gateway servers that you want to support:

If the network is completely disconnected from the Internet, push notifications cannot be delivered via the standard OS/browser services, which is what we support.