Push overview
Send and manage mobile and web push notifications from the OneSignal dashboard or API across platforms with powerful targeting and personalization features.
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:
Mobile push
Configure iOS, Android, Huawei, and Amazon push notifications.
Web push
Enable push for Chrome, Firefox, Safari, and Edge.
Mobile SDK Setup
Add OneSignal to your mobile app codebase.
Web SDK Setup
Add OneSignal to your website.
Migrating to OneSignal
Learn how to migrate to OneSignal.
Ask users for push permission
A great opt-in experience maximizes your push audience:
Mobile: Prompt for push permissions
Best practices for prompting push permissions in apps.
Web: Prompt for push permissions
Customize the prompt timing and message for web push.
Mobile: iOS Provisional Push Notifications
Use provisional push for a low-friction opt-in on iOS.
Mobile: Android Notification Categories
Organize notifications for Android user control.
Features & advanced use cases
Message Personalization
Add dynamic content to personalize messages for each user.
Multi-Language Messaging
Send push notifications in multiple languages.
Throttling
Control notification delivery speed.
Frequency Capping
Limit the number of push notifications per user.
Data & background notifications
Send data-only notifications for background tasks.
VOIP notifications
Send VOIP-specific push notifications.
Analytics
Track performance and optimize engagement:
Push message reports
Use built-in analytics for message-level reporting.
Event Streams
Stream events to your data warehouse or BI tools.
View messages API
Pull message analytics.
Analytics overview
Understand analytics capabilities in OneSignal.
Send push notifications
Choose your preferred sending method:
A/B Testing
Test up to 10 message variants.
Journeys
Build automated and personalized message flows.
API
Send programmatically via the REST API.
Dashboard
Continue below to learn how to send push from the OneSignal dashboard.
Steps for sending messages with OneSignal:
Select the message channel
Go to Messages > Push > New Push or use the Create message API.
How to send push from the OneSignal dashboard.
Choose a composition method
- Start from scratch
- Use Templates or saved layouts
Select blank push or use an existing Template.
Set a name and label
Optionally set internal metadata for tracking.
- API:
name
Set an audience
Include or exclude Segments:
- Send to 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 subscriptions are automatically removed.
Sending from the dashboard uses Segments.
Targeting method | Dashboard | API |
---|---|---|
Segments | ✅ | ✅ |
Filters (API only) | ❌ | ✅ |
Aliases (API only) | ❌ | ✅ |
Schedule and delivery options
Scheduling and delivery options in the OneSignal dashboard.
- Scheduled Delivery: Send at a specific time up to 30 days in advance (
send_after
) - Intelligent Delivery: Optimize per user behavior (
delayed_option: last-active
) - Timezone Delivery: Deliver at local time (
delayed_option: timezone
) - Throttling: Limit delivery speed (
throttle_rate_per_minute
) - Frequency Capping: Limit per-user messages (
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.
1: Title, 2: Message, 3: Icon, 4: Image, 5: Action buttons, 6: App name or browser, 7: Timestamp received
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.
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
– iOSbig_picture
– Androidchrome_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 URLapp_url
: deep link (e.g.your-app://screen
)web_url
:http
orhttps
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
- API:
- 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:
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:
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:
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.
iOS limitation: APNs stores only the most recent notification while offline. Earlier ones are dropped.
Learn more →
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.