Push overview

Send and manage mobile and web push notifications with OneSignal using the dashboard or API, with targeting, personalization, and scheduling.

Push notifications re-engage Users with timely, personalized content across devices — even when they’re not actively using your app or website.

Watch how push notifications drive the highest engagement, or skip ahead to get started.

OneSignal provides a complete platform to manage push notifications across mobile, web, and desktop:

• Send campaigns and transactional messages from the dashboard or API
• Automate multi-channel flows with Journeys
• Target Users precisely using Segments, filters, or User data
• A/B test and optimize message performance
• Personalize content with User attributes and dynamic content
• Integrate with your stack — HubSpot, Mixpanel, Amplitude, Zapier, and more

---

Push setup

Before sending push notifications, complete the platform setup, configure permission prompts, and enable the features you need.

Platform setup guides

Mobile push setup

End-to-end setup for iOS, Android, Huawei, and Amazon push notifications.

Web push setup

Enable push for Chrome, Firefox, Safari, and Edge.

Mobile SDK setup

Integrate the OneSignal SDK into your mobile app.

Web SDK setup

Integrate the OneSignal SDK into your website.

Migrating to OneSignal

Migration steps from Firebase, Airship, Braze, and other providers.

macOS app support

Configure OneSignal for macOS apps.

Windows app support

Configure OneSignal for Windows desktop apps.

watchOS and Wear OS support

Add OneSignal to Apple Watch and Wear OS devices.

Permissions

A well-designed opt-in experience maximizes your push audience.

Mobile push prompts

Build pre-permission prompts and best practices for mobile apps.

Web push prompts

Customize prompt timing and messaging for web push.

iOS provisional push

Deliver silent notifications to the notification center before prompting for full permission.

Android notification categories

Let Android Users customize how they receive notifications from your app.

Features and advanced use cases

Message personalization

Add dynamic content to personalize messages for each User.

Multi-language messaging

Send push notifications in each User’s preferred language.

Throttling

Control notification delivery speed for large audiences.

Frequency capping

Limit the number of push notifications per User.

Data and background notifications

Send data-only notifications for background tasks.

VoIP notifications

Send VoIP-specific push notifications for calling apps.

---

Send push notifications

Send push from the dashboard, automate with Journeys, or send programmatically via the API.

Dashboard

Compose and send push notifications from the OneSignal dashboard.

API

Send push notifications programmatically via the REST API.

Journeys

Build automated, multi-step push and multi-channel flows.

A/B testing

Test up to 10 message variants to optimize performance.

Send from the dashboard

1. Select the message channel

   On the left sidebar, select + Create… > Push or at the top right corner, select New Message > New Push. You can also navigate to Messages > Push to see previous messages.

   
2. Choose a composition method

   Start from scratch or use a pre-built template.

3. Set a name and label

   Add internal tracking metadata to organize your messages. API equivalent: name.

4. Set the target audience

   Select which Users receive the message. You can include and exclude Segments to target specific groups.

   • Send to default segment: Defaults to all “Subscribed Users” if no segment is set.
   • Send to specific segments: Include and exclude segments explicitly. Multiple segments have an “OR” relationship; duplicate Subscriptions are automatically removed.

   

   Targeting method	Dashboard	API
   Segments	Yes	Yes
   Filters (API only)	No	Yes
   Aliases (API only)	No	Yes

Schedule and delivery options

Watch how timing impacts push notification performance, or see the delivery options below.

Schedule notifications up to 30 days in advance. Push can be sent to Users in their respective timezones or 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: Optimizes send times based on the User’s session activity. API: delayed_option: last-active
• Timezone delivery: Deliver at local time. API: delayed_option: timezone and 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.

Use the AI message composer to quickly generate notification titles and body text. Adjust tone and content to match your brand in a few clicks.

Title

Top-most customizable text of the notification. Text appearance is controlled by the operating system.

• 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: AI message composer, 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. Style is set by the operating system.

• Required unless sending a background notification
• Supports: AI message composer, emojis, message personalization, multi-language messaging
• Recommended 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: 1024×512px (2:1 aspect ratio)
• Max size: 1 MB, max width: 2000 px
• Not supported on Safari (macOS/iOS) or macOS Notification Center
• Must be tapped or expanded on mobile to view
• Supported formats: PNG, JPG, GIF (animated only on iOS)
• API: ios_attachments (iOS), big_picture (Android), chrome_web_image (Chrome web)
• See Images and 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: url (single universal URL), app_url (deep link, e.g. your-app://screen), web_url (http/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
• Huawei: Badge displayed as a number or dot. API: huawei_badge_class, huawei_badge_set_num, huawei_badge_add_num
• Web (Chrome/Android): Icon shown in Android status bar; must be a 72×72 alpha PNG. API: chrome_web_badge
• 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 and click listeners in the mobile SDK and web SDK
• Dashboard supports only simple key-value data; use the API with data to send nested JSON
• Max total payload: ~4 KB; data field: up to 2048 bytes
• See Notification payload reference

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

For example, a weather app sends three alerts. If the User opens their device after all three, only the last message displays.

Web push topic (web push)

Avoid replacing older web notifications by using unique web_push_topic values. Notifications with different topics remain visible independently. Max length: 64 characters. API: web_push_topic

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 priority, FCM priority

Time to live (TTL)

How long to keep a message if the device is offline. Default: 3 days. Range: 0–2,419,200 seconds (28 days). API: ttl

If a User is offline and the TTL expires, the message is discarded. Set ttl: 0 for messages that should never be delivered late.

iOS limitation: APNs stores only the most recent notification while the device is offline. Earlier notifications are dropped. Learn more.

Notification grouping

Android and iOS automatically group notifications after a device receives 4 or more from your app.

• iOS: Use thread_id in the API to group messages together.
• Android: Use android_group in the API, or set the “Group Key” in the dashboard. For advanced customization, see Android NotificationExtenderService and Android’s group notify guide.

---

Cancel push notifications

Cancel a message if it has not been Delivered yet. OneSignal stops sending the message to all Subscriptions not already in the queue. This does not remove the message from devices that already received it.

In the Message Report, select Actions > Cancel, or use the Cancel Message API.

Remove a push notification from a device

Once delivered, you can only replace a push notification if you set a Collapse ID or Web push topic. Without one of these, the notification cannot be replaced or removed.

---

Analytics

Track push performance and optimize engagement.

Push message reports

Message-level delivery, open rate, and click-through reporting.

Analytics overview

All analytics options available in OneSignal.

Event Streams

Stream push events to your data warehouse or BI tools in real time.

View messages API

Pull message analytics programmatically via the REST API.

---

FAQ

What platforms does OneSignal push support?

OneSignal supports push on iOS (APNs), Android (FCM), Huawei (HMS), Amazon (ADM), web browsers (Chrome, Firefox, Safari, Edge), macOS, and Windows. See the platform setup guides above.

How do I test push notifications before sending to Users?

Set up test Subscriptions to verify delivery, rendering, and deep links without affecting real Users. You can also send to a single-user segment for quick testing.

Why are my push notifications not showing?

Common causes include missing or expired platform credentials, Users not granting permission, or device-level settings like Do Not Disturb. See Notifications not shown or delayed for a full troubleshooting checklist.

What is the maximum push notification payload size?

The total payload size is approximately 4 KB across all platforms. The data field supports up to 2048 bytes. Exceeding these limits may cause notifications to be truncated or rejected.