- 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.
Choose a composition method
- Start from scratch or use the AI message composer.
- Use a pre-built template
Delivery schedule and optimization
See how timing impacts push notification performance.| Option | Description | API field |
|---|---|---|
| Send immediately | Deliver to all recipients now. | — |
| Scheduled | Send at a specific time, up to 30 days in advance. | send_after |
| Option | Description | API field |
|---|---|---|
| Everyone at the same time | All recipients receive the email at once. Best for urgent messages. | — |
| Intelligent Delivery | Sends at the optimal time for each user based on their session activity. | delayed_option: last-active |
| Custom time per timezone | Sends at a set local time in each user’s timezone. | delayed_option: timezone, delivery_time_of_day |
| Override Throttling | Change the throttle rate. | throttle_rate_per_minute |
| Override Frequency capping | Disable frequency capping for this message. | 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.- 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.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.xmlunder<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
datato send nested JSON - Max total payload: ~4 KB;
datafield: up to 2048 bytes - See Notification payload reference
Collapse ID (mobile push)
Replace earlier notifications with a newer one if they share the samecollapse_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 uniqueweb_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_idin the API to group messages together. - Android: Use
android_groupin 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 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 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. Thedata field supports up to 2048 bytes. Exceeding these limits may cause notifications to be truncated or rejected.