Push notifications (also known as remote notifications) are one of the most effective ways to re-engage users with timely, personalized content across devices—even when they’re not actively using your app or website.

OneSignal provides a complete platform to manage push notifications across mobile, web, and desktop. Whether you’re a marketer, product manager, or developer, you can launch high-impact push campaigns in minutes.

​

What you can do with OneSignal Push

• Send marketing campaigns and transactional messages from the Dashboard or API
• Build automated push and multi-channel flows with Journeys
• Target users precisely using Segments, filters, or user data
• A/B test and optimize performance
• Personalize messages with user attributes and Dynamic Content
• Integrate with CRMs & tools like HubSpot, Mixpanel, Amplitude, Zapier, and more

​

Push setup

Before sending notifications, complete platform-specific setup:

​

Ask users for push permission

A great opt-in experience maximizes your push audience:

​

Features & advanced use cases

​

Analytics

Track performance and optimize engagement:

​

Send push notifications

Choose your preferred sending method:

Steps for sending messages with OneSignal:

​

Schedule and per-user delivery

Schedule notifications up to 30 days in advance. Push can be sent to users in their respective timezones or intelligently optimized based on each user’s behavior.

• Scheduled Delivery: Send at a specific time up to 30 days in advance (API: send_after)
• Intelligent Delivery: Optimize per user behavior (API: delayed_option: last-active)
• Timezone Delivery: Deliver at local time (API: delayed_option: timezone & delivery_time_of_day)
• Throttling: Limit delivery speed (API: throttle_rate_per_minute)
• Frequency Capping: Limit per-user messages (API: enable_frequency_cap)

​

Design properties

Push messages can either display user-facing content or perform background operations.

• Display notifications: Require a message and may include a title, image, action buttons, and other visual elements.
• Background/data-only notifications: Omit the message, include content_available, and optionally additional data.

​

Title

Top-most customizable text of the notification. Text appearance is controlled by the operating system (no custom fonts or styling like bold or italics).

• Required for web push and Huawei
• Defaults to site name on web if not set
• Recommended limit: 25–50 characters (mobile), 60–80 (web)
• Supports: emojis 👍, message personalization, multi-language messaging
• API: headings

​

Subtitle

Secondary text supported on iOS and macOS only (via APNs). Not available on Android or web.

• Recommended limit: 25–50 characters
• Supports: emojis 👍, message personalization, multi-language messaging
• API: subtitle

​

Message

Main content of the notification. Does not support custom fonts or styling such as bold, italics or underlines. The style is set by the operating system.

• Required unless sending background notification
• Supports: Emojis 👍, Message Personalization, Multi-language messaging
• Limit: ~150 characters
• API: contents

​

Icons

Customize small and large icons on Android and web. iOS always uses the app icon.

• See Notification icons

​

Image

Add a large image to notifications on Android, iOS, and Chrome for Windows/Android.

• Recommended size for all platforms: 1024×512px (2:1 aspect ratio)
• Max size: 1 MB, max width: 2000 px
• Not supported on Safari (macOS/iOS) or macOS Notification Center
• Image must be tapped or expanded on mobile to view
• Supported formats: PNG, JPG, GIF (animated only on iOS)
• API parameters:
  • ios_attachments – iOS
  • big_picture – Android
  • chrome_web_image – Chrome web
• See Images & Rich Media

​

App name

The name of the app displaying the notification.

• iOS: Set in Xcode under Display Name; requires device restart to update
• Android/Amazon/Huawei: Set in AndroidManifest.xml under <application android:label="YOUR APP NAME">
• Web: Shows the site name and/or browser

​

Feature properties

​

Action Buttons

Add interactive buttons to the push notification.

• Supported on Android 4.1+ and iOS 8.0+
• See Action buttons

​

Launch URL

Control where users go when tapping the notification.

• API parameters:
  • url: single universal URL
  • app_url: deep link (e.g. your-app://screen)
  • web_url: http or https web link
• See URLs, Links, and Deep Links

​

Badges

Show dots or badge numbers on app icons.

• iOS: Red numeric badge; can set, increment, or clear
  • API: ios_badgeType, ios_badgeCount
• Android: Requires notification categories
• Web (Chrome/Android):
  • Icon shown in Android status bar
  • Must be a 72×72 alpha PNG
  • API: chrome_web_badge
  • Example icon →
• See Badges

​

Sound

Play a sound when the push is delivered.

• iOS: Set with sound
• Android: Set via notification categories
• Web: Not available

​

Additional data

Add custom key-value pairs to the payload for SDK handling.

• Used by:
  • Mobile service extensions
  • Click listeners in mobile SDK and web SDK
• Dashboard supports only simple key-value data
• To send nested JSON, use the API with data
• Payload size:
  • Max total size: ~4KB
  • data field: up to 2048 bytes
• OSNotification payload →

​

Collapse ID (mobile push)

Replace earlier notifications with a newer one if they share the same collapse_id.

• Max length: 64 characters
• API: collapse_id

Example: A weather alert system might send the following notifications:

Notification 1. sent at 1:41 PM — "A storm is approaching. Grab an umbrella!"  
Notification 2. sent at 2:20 PM — "Storm clearing up. Sunshine expected."  
Notification 3. sent at 2:44 PM — "Storm has passed. Enjoy the sunshine!"

If the user opens their device at 4:00 PM, only the last message will display.

​

Web push topic (web push)

Avoid replacing older notifications on web by using unique web_push_topic values.

• Max length: 64 characters
• API: web_push_topic

Example:

Notification 1. web_push_topic: "breaking-news"   → Notification 1
Notification 2. web_push_topic: "breaking-news"   → Notification 2 (replaces #1)
Notification 3. web_push_topic: "sports"          → Notification 3 (stays visible)
Notification 4. web_push_topic: "weather"         → Notification 4 (stays visible)

​

Priority

Set the urgency of the push, especially in battery-saving modes.

• High (recommended): Immediate, alert-based messages
• Normal: Used for background/data notifications

API: priority Platform docs:

• APNs apns-priority
• FCM priority

​

Time to live (TTL)

How long to keep a message if the device is offline.

• Default: 3 days
• Range: 0 to 2,419,200 seconds (28 days)
• API: ttl

If a user is offline and the TTL expires, the message is discarded.

Example: Set ttl: 0 — If the device is offline when the message is sent, it will never be delivered.

​

Notification grouping

Android and iOS will automatically group notifications together after the device receives 4 or more notifications for your app.

iOS notification grouping

• Use the thread_id REST API property with the same value to group messages together.

Android notification grouping

• Use the android_group REST API property with the same value to group messages together.
• Android “Group Key” can also be set when sending push messages from the dashboard.

If you need more customizations see the Android NotificationExtenderService to group messages and add another NotificationExtenderService to update the summary notification. See Android’s Group Notify Guide for more details.

Note there are some limitations that Android 7+ has for these summary notifications. You can only modify the text, accent color and small icon (not large icon). However, you can still modify the children.

​

Cancel push notifications

You can cancel a message if it has not been Delivered yet. OneSignal will stop sending the message to all Subscriptions that have not been added to the queue. This does not remove the message from a device if already delivered.

In the Message Report, select Actions > Cancel or use the Cancel Message API to cancel a message.

​

Remove push notification from device

Once a push has been delivered, there are few options for removing it from a user’s device. You can replace a push notification with a new one if you set a Collapse ID or Web push topic.

If you do not set a Collapse ID or Web push topic, you cannot replace it.