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

Sending Push Messages

OneSignal features - Sending Push Messages

📘

Options for Sending Push Notifications

This page explains how to send a push notification from the OneSignal Dashboard. For other options to send push see:

Messages > New Push

Step 1. Audience

Selecting Users

There are two options for selecting which devices are eligible to receive notifications.

OptionDescription
Send to Subscribed UsersSends to your default segment which you can set. Otherwise, this defaults to all subscribed devices.
Send by SegmentIf you've set up Segments, you can both include and exclude them from receiving the message.

- Targeting multiple segments, OneSignal will automatically filter out duplicate user records so the device only gets one push.

- Excluding a segment, any device in the excluded segment will not get the push notification.

📘

Sending To Test Devices

Testing notification layout is recommended and can be done easily in Step 2: Send To Test Device button.

Step 2. Message

Enter the message title, subtitle (iOS), message, image and launch url in this section.

OptionDescription
Multiple Languages Select Add Languages button to add Supported Languages.

Add Any Language for default across all fields.
Title Web: Defaults to the Site Name set in Settings.
Android & iOS: Not required.
Huawei: required.
Subtitle Supported on iOS mobile apps.
Message Required for all platforms.
ImageThis will populate the image for all applicable platforms. See Notification Images Guide for details on recommended sizing.

You can override images for specific platforms in the below platform settings section.
Launch URL The URL a user will be directed when clicking the push. Will open the web page or an in-app browser on Mobile Apps.

Details on Deep Linking see Links, Deep-links and URLs.

📘

Notification Appearance Guide

More details on Character Limits, Emoji Support and more in our Push Notification Guide.

Sending to Test Devices

If you setup test devices you can send to them with Send To Test Device button. Any scheduling options like Intelligent Delivery will be used in the test message. See Test Messages sent in Delivery.

Platform Settings

This section shows you options available to specific platforms, and customize the presentation and features of those notifications. Tips for each option will appear on the right when hovering over each option on the left.

Each Platform can be disabled. If the platform switch is turned off, no devices of that platform will get the push, even if targeted in the Audience Segment.

iOS Options

iOS OptionsDescription
Badges- Don't set - no badge set
- Set to - specify exact badge count
- Increase by - increment the badge count by your desired amount
SoundThe sound that plays when this notification is received by the device. If no sound is specified, the device's default sound will play.
Content AvailableFor native iOS apps only. Wakes your app when the notification is received so you can do work in the background. See also Apple's 'content-available' documentation for more details.
CategoryUse with UNNotificationContentExtension for action buttons.
MediaRich media attachment. Image, sound, or video to show when viewing the notification.
Mutable ContentNative only code. Allows you do modify the notification from your app before it is displayed. See Apple's 'mutable-content' documentation for more details

Android Options

Android OptionsDescription
CategoryHighly recommended for Android 8+ devices. Settings will carry over to android 7 and lower.
SoundThe sound that plays when this notification is received by the device. If no sound is specified, the device's default sound will play.

Recommended: Use Notification Categories instead.
LED ColorSets the device's LED notification light (if the user's device has one). If no LED Color is specified, the device's default color will show.

Recommended: Use Notification Categories instead.
Lockscreen VisibilityOnly applies to apps targeting Android API level 21+ running on Android 5.0+ devices.

Recommended: Use Notification Categories instead.
Small IconDefaults to a bell unless specifically added. Icon shown in the status bar. Also show to the left of the notification text unless a large icon is set. Do not include a file extension.
Large IconIcon that shows to the left of the notification text. Include a file extension or upload your icon. Do not include a file extension.
Big PictureShows up in an expandable view below the notification text.
Group KeyNotifications with the same Group Key will be stacked together as a single summary notification with the number of unopened notifications.
Group MessageOnly applies to Android 6.0 and older. By default '# new messages' will shown on the device when 2 or more notifications are received with the same group key. Enter a custom message with '$[notif_count]' in the message text so the count can be replaced.
Background DataLegacy option for pre 3.0 versions of the OneSignal Android SDK. Read our documentation for a new way to set this up.

Web Options

Certain browsers have limited features. Most features are Chrome only.

Web Push OptionDescription
IconDefaults to icon set in the Web Push Settings
ImageDisplays a large image on the notification content (Windows or ANDROID only).
BadgeReplaces the Chrome browser icon with your monochrome badge icon. The minimum recommended size is 72x72 pixels.
Action Buttons Extra buttons that show on a push that can direct a user to a different URL.

Advanced Settings

OptionDescription
Additional DataCustom key : value data pairs sent to your app through the notification. Use data when sending from our REST API.

More details on this below in our FAQ How To Use Additional Data.
Collapse Key/IDCurrent notifications with the same id/key will be replaced instead of showing a whole new notification on the device. Limit of 64 characters.
PrioritySets the urgency and can override certain device and browser settings. Some devices de-prioritize notifications to show at a later time if the battery is low. This will attempt to show the notification even if the device has low power.

For Android 8+ you must use Importance instead. This is set in the Notification Categories and this will override the Priority flag for Android 7 and lower devices.
Time To LiveThe default time is 259,200 seconds (3 days) but can be any value from 0 to 2,419,200 seconds.

The notification will expire if the device remains offline for these number of seconds.

Affects iOS, Android, and Chrome Web Push.
Action ButtonsAndroid and iOS mobile apps only.

Buttons show on the notification itself. Works on iOS 8.0+, Android 4.1+.

Step 3. Scheduling

You can schedule a notification up to 30 days in advance.

The OneSignal Dashboard detects timezone according to your Operating Systems time.

Selecting Begin sending at a particular time will allow you to set when the notifications will start to be sent. That time is displayed on the bottom right circled in red in the image.

Notifications will be delivered to users based on the Per-User Optimization selection.

Intelligent Delivery

Intelligent Delivery is a unique feature of OneSignal that optimizes notification delivery time based on when each user most frequently access your app or website and is the best way to optimize notification open rates.

Each time a device accesses your website or mobile app with our SDK active, our SDK tracks their Last Session and notes the hours in which these devices most commonly return. This is based on up to a 3 month rolling average of a user's past actions.

With Intelligent Delivery, each user will receive your notification within 24 hours of you initiating delivery. For example, you sent a message at 7 PM and the user is most likely to open the app/site at 1 PM, the notification will be delivered 18 hours later (at 1 PM the following day). If your notification is very time-sensitive we instead recommend either Sending Immediately (which initiates delivery right away to all users, regardless of their activity or timezone) or Time Zone optimization (to deliver at the same time across user timezones).

Optimize by the user time zone

Once you schedule the notification to go out, you can set the delivery based on each device's set timezone. This is based on the device's settings.

So if you want a notification to be delivered to all your users in different timezones at 1PM for example, you can do this with OneSignal!

Keep in mind that if a timezone has already passed when you start sending this notification, they will get the notification at the set timezone, the next day. So it is important to make sure you start sending 24 hours before


FAQ

How do I send a notification to a single user?

For Developers

If you're looking to send notifications to a specific user device:

1. Get the user's userId/playerId with the getUserIds method on the Web Push SDK or getPermissionSubscriptionState method on the Mobile SDK you are using.
You can also send OneSignal your own unique user ids as "external_user_ids" using our setExternalUserId method on all our SDKs.

  • For testing you can use the 'Player ID' shown in All Users (you can force kill your app and open it again to bring your device to the top of the list.)

2. You can use this user id while in the app to send with our postNotification method and/or we recommend saving this id to your database. More in our Internal Database, DMP, & CRM guide.

3. Set include_player_ids (or include_external_user_ids) to the userId on the PostNotification SDK method or on the Create notification POST REST API call.

More details can be found in our User-User Messages or Transactional Messages guides.

How long can notifications be?

See Concepts: Appearance.

How to schedule recurring notifications?

Using the above steps, you can setup recurring notifications ahead of time. One at a time.
It is better to use our OneSignal API for this, but this is still only one at a time.

You can also setup Automated Messages but there is no guarantee on when exactly the user will receive them.

Another option you have is to use the Zapier | OneSignal integration.

Can notifications get re-ordered with the Intelligent Delivery Option?

Yes, if you send multiple notifications with Intelligent Delivery that should be delivered on the same day, then users may get the notifications in different orders.

This is due to how our SDK interprets the rolling average of a user's predicted-active time on your site or app.

For example, if my current predicted-active time is 3:00pm and you send notification1 to me with Intelligent delivery. Our system will set this notification to be received by me around 3:00 pm.

If I visit your site or app at 2:00 pm. My predicted-active time may now change to an earlier time, so notification2 may be received before notification1.

How can I use Additional Data?

OneSignal allows up to 2048 bytes of data to be passed within the Additional Data or API data parameter of a notification.

This is generally used for Deep Linking or passing data into the push to run code upon receipt using our SDK Handle Notification Methods.

When using the Dashboard to send the push, this can only take key: value pairs of data. To send nested JSON object as a value, you would need to use our API Create Notification POST call.

Updated 29 days ago



Sending Push Messages


OneSignal features - Sending Push Messages

Suggested Edits are limited on API Reference Pages

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