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

The Messages page shows you recent messages you've sent or scheduled, and links you to New Message and Sent Messages.

To access New Message, just click on New Push:

New Message Page

Dashboard > Messages > New Message

From here you can configure, preview, and send your push messages.

Step 1. Audience

Selecting Users

There are three options to select which users receive your messages


Send to Everyone

Sends to all users.

Send by Segment

If you've set up User Segments, you can both include and exclude segments to send to.

Send to Test Users

Allows you to select which Test Users to send to. Useful when you're testing new notifications and what to see how they look on devices.

Step 2. Message

Enter the message contents in this section.

Multiple Languages

The default notification title and contents are sent to:

  • All English users
  • All other users you do not specify a language-specific title and content for

You can click the pencil icon to add a language-specific title and content:

For example, to target Spanish, Turkish, and Finnish users:

  1. Fill in the default Title and Content. This is always required, and is sent to any users who are not Spanish, Turkish, or Finnish (e.g. English or other users).

  2. Click Add another language and select Spanish, Turkish, and Finnish. Supported Languages

  3. Fill in the Title and Content for each of your three new languages.

Step 3. Options

This section shows you options to send notifications 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.

Platform / Option

Send to iOS Subscribers?

Send to iOS devices.

Send to Android Subscribers?

Send to Android devices.

Send to Amazon Fire Subscribers?

Send to Amazon devices.

Send to Windows Phone 8.0 (MPNS) Subscribers?

Send to Windows Phone 8.0 devices.

Send to Windows Phone 8.1 (WNS) Subscribers?

Send to Windows Phone 8.1 devices.

Send to macOS Subscribers?

Send to macOS devices.

Send to Chrome App Subscribers?

Send to Chrome Apps & Extensions. This is not Web Push

Send to Chrome Web Subscribers?

Send to Chrome browsers (Web Push).

Send to Safari Web Subscribers?

Send to Safari browsers (Web Push).

Send to Firefox Web Subscribers?

Send to Firefox browsers (Web Push).

Include Additional Data?

Default is OFF

Custom key values pairs sent to your app when the notification is opened. See our SDK API documentation for details on how to read the data in your app.

Launch URL?

Default is OFF

Opens a web browser to the URL when the user taps on the notification.

Collapse Key/ID

Current notifications with the same id/key will be replaced instead of showing a whole new notification on the device. Limit of 64 characters.

Works on iOS, Android

Time To Live

Default is 259,200 seconds (3 days)

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

Affects iOS, Android, and Chrome Web Push.

Include Android / iOS Action Buttons?

Default is OFF

Buttons show on the notification itself. Works on iOS 8.0+, Android 4.1+, and ChromeApps using our official SDKs.

Include Chrome Web Push Action Buttons?

Default is OFF

Up to two actions buttons can be shown on a web push notification. Action button icons are only supported on Chrome in Windows.

By default, all device platforms are enabled. You can choose whether to send your notification to individual platforms by toggling the switch next to the platform name:

This collapses the section and does not send to devices on selected platform. For example, Chrome Web users will not receive notifications when the menu looks like this:

Additional Data

Key : Value pairs that can be used to run some code inside your app or site when a notification is received or clicked. Same as the API data parameter.

Common example: Opening a URL inside your app's web view.

Pass a Key : Value pair "openURL" : "" and in the notificationOpenedHandler of your SDK, you can access that value and send it to the part of your app that you want.
Often used with deep linking


To send a link, find the Launch URL option and type in the link. Be sure to include the full URL including http:// or https://. This will open an external link when the notification is tapped. To learn more about links, including deep linking, take a look at our Links documentation

iOS - To have links open in an in-app browser, take a look at the key settings in the iOS Native SDK.

Collapse ID/Key

Adding a collapse_id parameter to a notification marks it to be removed from the device when another notification is sent with the same collapse ID.

For example, sending notification1 with a collapse_id = "collapse".

Then, send notification2 with the same collapse_id = "collapse".

If the user did not open notification1 yet, then notification2 will override and replace it.

Time To Live

The Time to Live or ttl parameter is an integer value in seconds that will shorten or lengthen the amount of time Google and Apple will "hold" the notification before they discard it.

If the user does not come online within the provided time, the notification will get deleted and will not show to the user.

The default time is 259,200 seconds (3 days) but can be any value from 0 to 2,419,200 seconds.

Step 4. Scheduling

Clicking the Schedule item lets you select among different notification delivery scheduling options:

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

You can set a desired time to start sending a notification using the "Begin sending at a particular time" option. This will make all the notifications go out to your users at the desired time.

OneSignal also provides Per-User Optimizations to target users in specific ways.

Intelligent Delivery

Target devices when they are most likely active to click the notification.

Learn more in Intelligent Delivery.

Optimize by the user time zone

This will send the notification to each user at the time you specify but for the user's timezone.

Learn more about Timezone Optimizations.

If you are not sure exactly when a notification will be sent, we show you in the tips on the right-hand side. For example, if you chose "Begin Sending at a Particular Time" and "Optimize by Timezone" options, it would look something like this:

Editing a message

Messages that are Scheduled or Canceled can be edited. Unless they are part of an A/B test


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.

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.