Why push notifications drive the highest engagement
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 push notifications, complete the following setup steps:- Platform-specific setup (mobile push, web push, Android, iOS, etc.)
- Configure permission prompts (allow users to opt-in to push notifications)
- Set up features & use cases (personalization, multi-language, throttling, etc.)
Mobile push
Web push
Mobile SDK Setup
Web SDK Setup
Migrating to OneSignal
macOS app support
Windows app support
WatchOS and WearOS support
Permission prompts
A great opt-in experience maximizes your push audience:Mobile: Prompt for push permissions
Web: Prompt for push permissions
Mobile: iOS Provisional Push Notifications
Mobile: Android Notification Categories
Features & advanced use cases
How to make every push notification count
Message Personalization
Multi-Language Messaging
Throttling
Frequency Capping
Data & background notifications
VOIP notifications
Analytics
Track performance and optimize engagement:Push message reports
Event Streams
View messages API
Analytics overview
Send push notifications
Choose your preferred sending method:A/B Testing
Journeys
API
Dashboard
Select the message channel

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
name
Set an audience
- 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.

Name, label, and audience segment selection interface
Targeting method | Dashboard | API |
---|---|---|
Segments | ✅ | ✅ |
Filters (API only) | ❌ | ✅ |
Aliases (API only) | ❌ | ✅ |
Schedule and per-user delivery
Timing is everything: How to send push notifications that drive action

Scheduling and delivery options in the OneSignal dashboard.
- 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
How to Turn Generic Push Notifications into High-Performing Messages
- 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: 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 such as bold, italics or underlines. The style is set by the operating system.- Required unless sending background notification
- Supports: AI message composer, 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 samecollapse_id
.
- Max length: 64 characters
- API:
collapse_id
Web push topic (web push)
Avoid replacing older notifications on web by using uniqueweb_push_topic
values.
- 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
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
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.
- 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.
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.
