Push notifications (also known as remote notifications) are the best way to capture user attention and communicate important updates, even when users aren't actively using your app or website. Notifications can contain text, images, sounds, and more.

You can send push notifications with OneSignal using several options:

• OneSignal Dashboard: Demonstrated in this guide.
• Create Messages API: Send push, email, and SMS via our server-side API.
• Journeys: Create push notifications, emails, in-app messages, and SMS with a no-code visual builder.
• Integrations like HubSpot, Integrately, Zapier, and WordPress.

---

Requirements

Before sending push notifications, ensure you have:

• Completed the Mobile SDK Setup and/or Web SDK Setup.
• Learn more about Mobile and Web Push Subscriptions.

---

Send push from the OneSignal dashboard

Navigate to New Message > New Push.

Optional: Provide a Message Name for internal identification. This corresponds to the API name parameter.

When sending from the OneSignal dashboard, you have additional options:

• Dynamic Content: Personalize notifications dynamically for individual users (Dynamic Content).
• A/B Testing: Test up to 10 notification variants (A/B Testing).
• Test Devices: Send notifications to specific test users (Set Test Subscriptions).

---

Select your target audience

You can target users via:

Segments

Select Segments to target or exclude specific users:

• Send to default segment: Uses your default segment; defaults to all "Subscribed Users" if none set.
• Send to specific segments: Include and exclude segments explicitly.

Multiple segments have an "OR" relationship; duplicate subscription are automatically removed.

---

Create your message

Push notifications can either display content for user interaction or update data in the background without displaying to the user.

• Displayable push notifications must include a message and any of the components outlined below.
• Data & background notifications must omit the message and include the Content Available flag and any additional data.

Title

The top-most customizable text of the notification. Push notifications do not support custom fonts or styling such as bold, italics or underlines. The style is set by the operating system.

• Maps to the API headings parameter.
• Required for web push. Defaults to the Site Name set in your Web SDK setup if not provided.
• Around 25-50 characters (mobile), 60-80 characters (web). Subject to the device and other parameters set in the message. For example, adding images and long Message text may cause the Title to truncate.
• Supports: Emojis 👍, Message Personalization, Multi-language messaging

Message

The localized text that provides the notification's main content. Push notifications do not support custom fonts or styling such as bold, italics or underlines. The style is set by the operating system.

• Maps to the API contents parameter
• Required unless sending Data & Background Notifications.
• Around 150 characters limit. Subject to the device and other parameters set in the message. For example, adding images and long Title text may cause the message to truncate.
• Supports: Emojis 👍, Message Personalization, Multi-language messaging

Subtitle

A subtitle supported by APNS for iOS push notifications only.

• Maps to the API subtitle parameter
• Only available for iOS push notifications.
• Around 25-50 character limit.
• Supports: Emojis 👍, Message Personalization, Multi-language messaging

Image

A large image available for Android and iOS mobile apps and Chrome web push notifications for Windows and Android only.

• Safari does not support images on macOS or iPhone.
• macOS doesn't support large images and just expands the icon.
• Image must be expanded to view on Android and iOS mobile push. See Images & Rich Media for details.
• Recommended image size: 480x240 or 1440x720 pixels or 2:1 aspect ratio.
  • Avoid images wider than 2,000 pixels and more than 1 MB in size.
• Filetype support: PNG, JPG, GIF*
  • Only iOS supports animated GIF. Android, Amazon, Huawei, Web GIF frozen on first frame.
• Maps to the API parameters:
  • ios_attachments - iOS mobile push
  • big_picture - Android mobile push
  • chrome_web_image - Chrome web push

Launch URL

The URL users are directed to upon clicking the notification. See URLs, Links, and Deep Links for more details.

• Maps to the API parameters:
  • url - for a single URL to be used across all platforms.
  • app_url - for a URL specific to mobile app's. Example schema: your-app://
  • web_url - for http and https URLs.

---

Platform settings

Each platform (Android, iOS, Chrome, Safari) offers unique notification capabilities that can be leveraged to create more engaging experiences for your users.

App name

• iOS: The Display Name in Xcode. If updated, users must restart the device to see this change take effect.
• Android, Amazon, Huawei: The property <application android:label="YOUR APP NAME"> set in the AndroidManifest.xml.

Media, Big Picture, Image

Same as using the Image field in the dashboard but you can specify different images to display for iOS, Android, and web.

Badges

Android and iOS support dots on your app icon enticing the user to click your app.

• iOS: Numeric badges displayed as red dots on your app icon. Supports: setting, incrementing, or clearing badge numbers. See Badges for details.
  • Maps to API parameters:
    • ios_badgeType
    • ios_badgeCount
• Android: Badges can only be set with the Android notification categories.
• Web: The badge is the small icon that shows in the Android status bar and is customizable on some versions of Chrome.
  • Must be an alpha-channel icon PNG. Example Chrome Badge icon.
  • Size 72x72 pixels.
  • API chrome_web_badge parameter.

Sound

Sound played upon receiving the notification. Defaults to device's standard notification sound if unspecified. Use nil to prevent the device from playing a sound. See Notification sounds for details.

For Android, use the Android notification categories instead of the Sound field.

Sound not supported for web push.

Content Available

Wakes your app in the background when the notification arrives, allowing background tasks. Required for Data & background notifications on Android and iOS.

Category

For iOS, this associates the notification with a UNNotificationCategory if setup in your app.

For Android, this sets the Android notification categories.

Target Content ID

Targets notifications to specific experiences in App Clips or to specific windows in multi-scene apps.

Icons

Customize the large and small icons displayed on Android mobile and web push. iOS uses the app's icon.

See Notification icons for details.

LED Color

Certain Android hardware devices have LED notification lights built-in, allowing notifications to trigger a colored notification light on a device upon receipt. Notification colors may be set on a per-message basis in the OneSignal dashboard, or via the OneSignal SDK/API.

Notification colors are set using ARGB Hex values (e.g. a red LED notification light would be in the format FF99000). If LED Color is not set, the light uses the device's default color.

Accent Color

Android only. Sets the accent color for notification text and icons (device dependent). Use Android notification categories instead.

Group Key, Relevance Score

For Android, group related notifications into an expandable summary notification. See Notification grouping for details.

For iOS, you can order the notifications in the group. See iOS: Relevance score for details.

Visibility, Notification Interruption Level

Manages notification visibility on the lock screen and when grouped.

Android, see Android notification categories.

iOS, see iOS: Focus modes and interruption levels.

---

Advanced settings

Additional data

Add custom key-value pairs of string data to the OSNotification payload to handle within the Mobile Service Extensions or Notification Click Listener method ( Mobile SDK reference, Web SDK reference ).

When sending notifications through the Dashboard, you can only add simple key-value pairs. To include a nested JSON object, use the data parameter of our Create message API.

Notifications support around 4KB of data, but only up to 2048 bytes can be included in the Additional Data field or API data property.

Collapse ID

For mobile app notifications.

Allow newer push notifications to collapse/replace older notifications for your app on the same device. Notifications with the same "collapse ID" (string value) will not stack or group. Maximum 64 characters. Maps to the API collapse_id parameter.

Example: You have an app with breaking news or a limited time sale and want to keep users informed on the latest updates. Set the collapse_id on these types of notifications to the same "ID" like "breaking-news" or "limited-time-sale". Then, every time you send a notification with this same "ID" it will collapse or replace the previous notification on the device. If your app sends three notifications, the following would happen:

1. Sent 1:41pm: "A storm looks like it's approaching. Better grab an umbrella!"

2. Sent 2:20pm: "The storm in your area seems to be clearing up. Expect sunshine soon."

3. Sent 2:44pm: "The storm has moved north and the sun will shine the rest of today!"

If a user does not open their device until 4pm, they would only see the third notification. If the user opened their device at 2pm and 4pm, they would see the first notification, and then at 4pm see the third notification.

Web Push Topic

For web push notifications.

Prevent newer web push notifications from collapsing/replacing older notifications for your site on the device. Notifications with different "topics" (string values) will not collapse each other. Maximum 64 characters. Maps to the API web_push_topic parameter.

Example: You do not specify the web_push_topic or you set the same "breaking-news" topic , each notification will be replaced by a newer notification:

• Notification 1 sent with web_push_topic: "breaking-news"
• Notification 2 sent with web_push_topic: "breaking-news"

Notification 2 will replace Notification 1.

• Notification 3 sent with web_push_topic: "sports"
• Notification 4 sent with web_push_topic: "weather"

Notification 2, 3 and 4 will all either be left on the screen or docked in the Notification Center.

Priority

Use High priority for urgent, time-sensitive notifications and Normal for less urgent messages like promotions, background data syncs, etc. See priority API parameter for details on sending via our API.

Push services like FCM and APNS attempt to deliver high priority messages immediately. However, excessive use may result in your notifications getting throttled or deprioritized to normal priority. FCM states:

High priority messages on Android are meant for time sensitive, user visible content, and should result in user-facing notifications. If FCM detects a pattern in which messages do not result in user-facing notifications, your messages may be deprioritized to normal priority or delegated for handling by Google Play Services.

Time to live

Applicable to iOS, Android, and Chrome Web Push.

The amount of time a push notification will be held by the push services (FCM, APNS, HMS, etc) if the user's device is offline. Defaults to 3 days. Range: 0–2,419,200 seconds (28 days). Maps to the API ttl property.

Does not remove the notification if delivered to the device. It only prevents the notification from displaying if the device does not have an internet connection before it is delivered.

Example: Set time to live to 0. Any device that does not have an internet connection when the message is sent will not receive the message. The push services will discard the message if it cannot be delivered.

iOS Limitation: Apple (APNS) only stores the most recent notification sent to a device on the APNS servers. If you send multiple notifications to an iOS device while it is offline, only the most recent notification will show when the device comes back online. See Apple's APNs Overview for more details.

Action Buttons

Interactive buttons displayed on notifications for Android (4.1+) and iOS (8.0+) apps. See Action buttons for more details.

---

Scheduling & delivery optimization

Configure message delivery timing:

• Scheduled Delivery: Set a specific date/time to start delivery. You can schedule messages up to 30 days in advance.
  • API send_after parameter
• Intelligent Delivery: Optimizes send times based on user activity patterns.
  • API delayed_option: last-active parameter
• Timezone Delivery: Schedule messages to arrive at the same local time across user timezones. Plan ahead based on your most eastern timezone.
  • API delayed_option: timezone & delivery_time_of_day parameters
• Throttling: Slows down how many push notifications are sent per minute. Ideal for large audiences and you want to limit how many users access your app.
  • API throttle_rate_per_minute parameter
• Frequency capping: Caps how many push notifications are sent to each Subscription per timeframe.
  • API enable_frequency_cap parameter

🚧

Limitations with Per-user optimization and Throttling

Intelligent Delivery and Timezone Delivery cannot be used simultaneously with Throttling.

---

FAQ

How can I schedule recurring notifications?

OneSignal offers several methods for scheduling recurring notifications:

• Journeys: Use the Journeys feature with the Time Windows node.
• API: Send notifications via the API Create Notification.
• Integrations: Use tools like Integrately or Zapier.

Can notifications be re-ordered with Intelligent Delivery?

Yes. With Intelligent Delivery, notifications scheduled for the same day may be delivered in a different order. This happens because our SDK continuously updates a user’s predicted-active time. For example, if the system initially sets your active time at 3:00 PM, notification1 will be scheduled for that time. However, if you visit the site at 2:00 PM, your predicted-active time may shift earlier, causing notification2 to arrive before notification1.