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:


Ask users for push permission

A great opt-in experience maximizes your push audience:


Features & advanced use cases


Analytics

Track performance and optimize engagement:


Send push notifications

Choose your preferred sending method:

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 methodDashboardAPI
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).

Subtitle

Secondary text supported on iOS and macOS only (via APNs). Not available on Android or web.

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.

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 – iOS
    • big_picture – Android
    • chrome_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.

Launch URL

Control where users go when tapping the notification.

  • API parameters:
    • url: single universal URL
    • app_url: deep link (e.g. your-app://screen)
    • web_url: http or 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
  • 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.

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

Example: A weather alert system might send the following notifications:

Notification 1. sent at 1:41 PM — "A storm is approaching. Grab an umbrella!"  
Notification 2. sent at 2:20 PM — "Storm clearing up. Sunshine expected."  
Notification 3. sent at 2:44 PM — "Storm has passed. Enjoy the sunshine!"

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:

Notification 1. web_push_topic: "breaking-news"   → Notification 1
Notification 2. web_push_topic: "breaking-news"   → Notification 2 (replaces #1)
Notification 3. web_push_topic: "sports"          → Notification 3 (stays visible)
Notification 4. web_push_topic: "weather"         → Notification 4 (stays visible)

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.