Skip to main content
Re-engage users with timely, personalized content across devices, even when they aren’t actively using your app or website. Watch how push notifications drive the highest engagement, or skip ahead to get started.

Why push notifications drive the highest engagement

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

You can send messages in several ways. The best option depends on your use cases.

Dashboard

Compose a message quickly within the dashboard.

Send via API

Send messages programmatically using the REST API.

Journeys

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

A/B testing

Test up to 10 message variants to optimize performance.

​
Send from the dashboard

Select the message channel

Select Create… then choose your message channel. You can also navigate to Messages or Templates to view previous messages.
OneSignal dashboard showing create message options

Create a new message in the OneSignal dashboard.

Choose a composition method

Set a name and label

Add internal metadata for tracking and reporting. API equivalent: name.

Select your audience

Choose which users receive the message. You can include and exclude segments to target specific groups. Defaults to all “Subscribed Users” if no segment is set.
Dashboard fields for message name, label, and audience segment selection

Name, label, and audience segment selection in the dashboard.

Design the message and send

Compose the notification using the design properties and feature properties below. Then send immediately or set a delivery schedule.

​
Delivery schedule and optimization

See how timing impacts push notification performance.

Timing is everything: How to send push notifications that drive action

Choose when OneSignal evaluates audience membership and begins delivering the message.
The send time determines the audience cutoff. OneSignal evaluates audience membership at that moment, and anyone in the audience receives the message regardless of per-user optimization settings.
Per-user delivery time: Set when each user in the audience receives the message. Delivery overrides: Override the app-level delivery defaults for this message only.
With Intelligent Delivery or Custom time per timezone, delivery spans a 24-hour period so every record in the audience can receive the message. If it is already 10 AM for a recipient when a 9 AM local-time message sends, they receive it at 9 AM the following day.

​
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, set content_available (iOS) or omit headings/contents (Android), and optionally include additional data.
Annotated diagram of a push notification with: 1 title, 2 message, 3 icon, 4 image, 5 action buttons, 6 app name or browser, 7 timestamp received

Anatomy of a web and mobile push notification

Legend: 1 Title, 2 Message, 3 Icon, 4 Image, 5 Action buttons, 6 App name or browser, 7 Timestamp received.
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.
Push platforms (Android, iOS, Huawei, Amazon) do not truncate titles or messages at a fixed character count. Where the text gets cut off depends on the device, orientation, and the user’s system text size (Accessibility mode). On Android, it also varies by launcher and manufacturer.OneSignal and the delivery services (APNs, FCM, and others) send the notification but don’t control how the device renders it, so no API or payload option can override truncation. The same text can show fully on one device and be cut off on another.

​
Subtitle

Secondary text supported on iOS and macOS only (via APNs). Not available on Android or web.
Subtitles truncate independently of the title, under the same operating system rendering rules. See the Title note above.

​
Message

Main content of the notification. Does not support custom fonts or styling. Style is set by the operating system.
The message body truncates under the same operating system rendering rules, and how much shows depends on whether the notification is collapsed or expanded. See the Title note above.

​
Icons

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

​
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.

​
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.

​
Additional data

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

​
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 (10, default and recommended): Immediate, alert-based messages.
  • Normal (5): Recommended for background and data-only 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.
Android device showing grouped push notifications from the same app

Grouped notifications on Android.

​
Huawei message type (Huawei)

Control how OneSignal delivers push to Huawei (HMS) devices. API: huawei_msg_type
  • data: The OneSignal SDK renders the notification client-side, enabling the full feature set (large image, action buttons) and Confirmed delivery. Not shown if the app is force quit.
  • message (default): HMS Core renders server-side; title and body only, but shows even if the app is force quit.
  • See huawei_msg_type and Data & background notifications.
huawei_msg_type=data is the HMS transport type, not a silent notification. A data-type push with visible content still displays a full notification.

​
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 message performance and 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 users 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.
This is different from on-screen title/body truncation. Payload size is a hard limit enforced by APNs/FCM before delivery. Title and body display truncation happens after delivery, on-device, and depends on operating system rendering. See Title above.