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. 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 Content

Details

Character Limits

How many characters are allowed and recommended per platform.
Emoji support is available across all platforms πŸ‘

Images

Large Images that appear with the notification. Supported by iOS, Android and Chrome on Windows/Android.

Icons

Supported on all platforms.

Sounds

Supported on iOS and Android mobile apps. Not customizable on Web Push.

Badges

Red dots with numbers for iOS and Android mobile apps. Web Push badges are the small icons on Chrome for Android.

Action Buttons

Custom 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 Behavior

Details

Deep-links and URLs

When click, send users to a custom url or view within the app.

Time To Live

How long the push is saved on the FCM/APNS/WNS servers if the user's device is offline.

Collapse Id

Replaces Notifications already present on the user's device if current notification contains this same collapse_id.

Notification Persistence

Requiring Web Push Notifications to be interacted with to be removed. Only available on certain platform versions.

Background and Data Notifications

Sending notifications without a visual appearance to the user. Mobile only.

Additional Data

Custom data sent within a push.


Content

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.

Platform

Title

Body

iOS

~25-50 (same for Subtitle)

~150

Android

~50

~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

Windows

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.

Firefox

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

MacOS

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:

Title

Body

Default

~40

~44

With Icon

~32

~35

With persistNotification

~30

~33

With persistNotification + Icon

~21

~24

Notification Center Default

~39

~80

Notification Center + Icon

~30

~62

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

Title

Body

Default

~40

~90

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.

Emojis

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.


Images

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 Push

Android

iOS

Filetypes

png, jpg, webp, gif*

jpg, jpeg, png, gif*

jpg, jpeg, png, gif

Resolution

Recommendations: 2:1 aspect ratio landscape

Max Width: 2000 pixels
Min Width: 300 pixels

Common sizes:
512x256px
1440x720px

Recommendations: 2:1 aspect ratio landscape

Max Width: 2000 pixels
Min Width: 300 pixels

Common sizes:
512x256px
1440x720px

Recommendations: 2:1 aspect ratio landscape

Max Width: 2000 pixels
Min Width: 300 pixels

Common sizes:
512x256px
1440x720px

Documentation

Web Push Image Guide

Android Big Picture Guide

iOS Rich Media Guide

OneSignal API Parameter

chrome_web_image

big_picture

ios_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

Icons

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 Push

Android

iOS

Documentation

Web Push Notification Icons Guide

Android Notification Icons Guide

Uses the app's default icon.


Sounds

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


Badges

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.

Updated about a month 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.