Sign in

v1

latestOpenAPI 3.1.02026-07-26497885.9 KB

Push notification

Send a message using the push notification channel.

post/notifications?c=push

Headers

Authorizationstring required

Your App API key with prefix Key . See Keys & IDs.

Request body

app_idstring required

Your OneSignal App ID in UUID v4 format. See Keys & IDs.

target_channel'push' | 'email' | 'sms'

The targeted delivery channel. Required when using include_aliases. Accepts push, email, or sms.

include_subscription_idsstring[]

Target users' specific subscriptions by ID. Include up to 20,000 subscription_id per API call. Not compatible with any other targeting parameters like filters, include_aliases, included_segments, or excluded_segments. See Sending messages with the OneSignal API.

included_segmentsstring[]

Target predefined Segments. Users that are in multiple segments will only be sent the message once. Can be combined with excluded_segments. Not compatible with any other targeting parameters like filters, include_aliases, or include_subscription_ids. See Sending messages with the OneSignal API.

excluded_segmentsstring[]

Exclude users in predefined Segments. Overrides membership in any segment specified in the included_segments. Not compatible with any other targeting parameters like filters, include_aliases, or include_subscription_ids. See Sending messages with the OneSignal API.

namestring

An internal name you set to help organize and track messages. Not shown to recipients. Maximum 128 characters.

template_idstring

The template ID in UUID v4 format set for the message if applicable. See Templates.

custom_dataobject

Include user or context-specific data (e.g., cart items, OTPs, links) in a message. Use with template_id. See Message Personalization. Max size: 2KB (Push/SMS), 10KB (Email).

big_picturestring

The local name or URL of the image to include in your Google Android notification. Users can expand the notification to view the images. See Images & Rich Media.

huawei_big_picturestring

The local name or URL of the image to include in your Huawei Android notification. Users can expand the notification to view the images. See Images & Rich Media.

adm_big_picturestring

The local name or URL of the image to include in your Amazon Android notification. Users can expand the notification to view the images. See Images & Rich Media.

chrome_web_imagestring

The URL of the image to include in your Chrome notification. Users can expand the notification to view the images. Supported on Chrome for Windows and Android. macOS does not support this parameter and instead expands the chrome_web_icon. See Images & Rich Media.

small_iconstring

The local name of the small icon to display in the Google Android notification. See Notification icons.

huawei_small_iconstring

The local name of the small icon to display in the Huawei Android notification. See Notification icons.

adm_small_iconstring

The local name of the small icon to display in the Amazon Android notification. See Notification icons.

large_iconstring

The local name or URL of the large icon to display in the Google Android notification. See Notification icons.

huawei_large_iconstring

The local name or URL of the large icon to display in the Huawei Android notification. See Notification icons.

adm_large_iconstring

The local name or URL of the large icon to display in the Amazon Android notification. See Notification icons.

chrome_web_iconstring

The URL of the icon to display in the Chrome web notification. Defaults to the resource set in the OneSignal dashboard. See Notification icons.

firefox_iconstring

The URL of the icon to display in the Firefox web notification. Defaults to the resource set in the OneSignal dashboard. See Notification icons.

chrome_web_badgestring

The URL of the icon to display in the Android notification tray for Chrome web notifications. Defaults to the Chrome icon. See Push.

android_channel_idstring

The UUID of the Android notification channel category created within your OneSignal app.

existing_android_channel_idstring

The UUID of the Android notification channel category created within your Android app.

huawei_channel_idstring

The UUID of the Android notification channel category created within your OneSignal app.

huawei_existing_channel_idstring

The UUID of the Android notification channel category created within your Huawei app.

huawei_category'MARKETING' | 'IM' | 'VOIP' | 'SUBSCRIPTION' | 'TRAVEL' | 'HEALTH' | 'WORK' | 'ACCOUNT' | 'EXPRESS' | 'FINANCE' | 'DEVICE_REMINDER' | 'MAIL'

The category you set for notifications sent to Huawei devices. The category chosen must align with an approved self-classification application. Subject to daily send limitations ranging from 2 to 5, depending on the specific third-level classifications the message falls under.

huawei_msg_type'message' | 'data'

Controls how OneSignal delivers the push to Huawei (HMS) devices. Both options can display a visible notification. Options: message - (default) HMS Core renders the notification server-side. Supports title and body only (no images, buttons, or other rich features). Displays even if the app is force quit, and if the device is offline it displays when the device reconnects within the ttl timeframe (usually 3 days). Does not support Confirmed delivery — Huawei reports receipts only in their own dashboard. data - HMS Core delivers the payload to the device and the OneSignal SDK renders the notification client-side. This enables the full OneSignal feature set (large images, action buttons, etc.) and supports Confirmed delivery. Because the SDK must run to render it, the notification is not shown if the app has been force quit (HMS Core will not start the app). This is also the type to use for silent data & background notifications on Huawei. Note: data here refers to the HMS transport type, not a silent notification — a data-type push with visible content still shows a full notification.

huawei_bi_tagstring

Define a tag for associating messages in a batch delivery, facilitating precise monitoring and analysis of delivery stats. This tag is returned to your server when Huawei's Push Kit sends a message receipt. You can set this parameter to track your push campaigns' performance and optimize your messaging strategy.

huawei_badge_classstring

Required for Huawei badge. The fully qualified class name of the app's entry Activity in the format <package_name>.<ActivityName> (e.g., com.example.myapp.MainActivity). Tells the Huawei system which app icon to apply the badge to. See Badges.

huawei_badge_set_numinteger

Sets the badge count to this exact number on Huawei devices. Range: 0–99. Set to 0 to clear the badge. If both huawei_badge_set_num and huawei_badge_add_num are provided, huawei_badge_set_num takes priority. Requires EMUI 10.0.0+ and Push SDK 10.1.0+. See Badges.

huawei_badge_add_numinteger

Increments the existing badge count by this number on Huawei devices. Range: 1–99. If omitted along with huawei_badge_set_num, defaults to incrementing by 1. See Badges.

priority10 | 5

Set the priority based on the urgency of the message. 10 - High priority. 5 - Normal priority. Recommended and default value is 10. APNs and FCM use this parameter to determine how quickly a notification is delivered and processed, particularly in power-saving modes. If sending data/background notifications, 5 (Normal priority) is recommended. For details, see APNs apns-priority and FCM priority.

ios_interruption_level'active' | 'passive' | 'time_sensitive' | 'critical'

The priority and delivery timing of iOS notifications based on their importance and the urgency with which they should interrupt the user. See iOS Focus modes and interruption levels.

ios_soundstring

The local name of the custom sound file to play when the notification is received instead of the default sound. See Notification sounds.

ios_badgeType'None' | 'SetTo' | 'Increase'

Set or increment the badge count on iOS devices. Use with ios_badgeCount. See Badges.

ios_badgeCountinteger

Use with ios_badgeType to determine the numerical change to your app's badge count. See Badges.

android_accent_colorstring

The ARGB Hex formatted color of the Android small icon background. For Android 8+ use Android notification channel category and android_channel_id.

huawei_accent_colorstring

The ARGB Hex formatted color of the Huawei small icon background. For Android 8+ use Android notification channel category and huawei_channel_id.

urlstring

The httpsURL that opens in the browser when a user interacts with the notification. See URLs, Links and Deep Links. Supports Message Personalization.

app_urlstring

Similar to the url parameter but exclusively targets mobile platforms like iOS, Android. Accepts values other than https but must use your-app-scheme:// protocol.

web_urlstring

Use with app_url if your app and website need different URLs. Accepts URLs with protocol https://

target_content_identifierstring

Direct the notification to a specific user experience within your app, such as an App Clip, or target a particular window in applications that use multiple scenes. See Apple's documentation.

thread_idstring

An ID to group notifications on Apple devices. Notifications with the same identifier are organized together in the notification center.

ios_relevance_scorenumber double

A value between 0 and 1, to sort the notifications from your app. The highest score gets featured in the notification summary. See iOS Relevance Score

android_groupstring

An ID to group notifications on Google Android devices. Notifications with the same identifier are organized together in the notification center.

adm_groupstring

An ID to group notifications on Amazon Android devices. Notifications with the same identifier are organized together in the notification center.

ttlinteger

The duration in seconds for which a notification remains valid if the device is offline. Any number between 0 and 2419200 (28 days). Defaults to 3 days. See Push: Time to Live.

collapse_idstring

An ID that replaces older notifications with newer ones that have the same identifier. For mobile push only. See Push: Collapse ID.

web_push_topicstring

An ID that prevents replacement of older notifications with newer ones that have different identifiers. For web push only. See Push: Web Push Topic.

dataobject

Bundle a custom data map within your notification, which is then passed to your app. See Push: Additional Data.

content_availableboolean

Allows for sending data/background notifications to the Android and iOS apps. Set to true and omit contents. Apple interprets this as content-available=1. See Data & background notifications.

ios_categorystring

Enable users to respond directly to a notification without launching the app. The Category will activate the corresponding Notification Content Extension in your app when the push is interacted with.

apns_push_type_overridestring

Use only for VoIP notifications. Corresponds to the apns-push-type. OneSignal automatically sets this value to alert or background based on the notification content. Pass voip to initiate VoIP calls or alert the user to incoming VoIP calls.

isIosboolean

Specifies if the notification should target iOS mobile apps only. Defaults to true. If set to true, all other platforms are disabled unless explicitly enabled.

isAndroidboolean

Specifies if the notification should target Google Android mobile apps only. Defaults to true. If set to true, all other platforms are disabled unless explicitly enabled.

isHuaweiboolean

Specifies if the notification should target Huawei mobile apps only. Defaults to true. If set to true, all other platforms are disabled unless explicitly enabled.

isAnyWebboolean

Specifies if the notification should target web push only. Defaults to true. If set to true, all other platforms are disabled unless explicitly enabled.

isChromeWebboolean

Specifies if the notification should target Chrome only. Defaults to true. If set to true, all other platforms are disabled unless explicitly enabled.

isFirefoxboolean

Specifies if the notification should target Firefox only. Defaults to true. If set to true, all other platforms are disabled unless explicitly enabled.

isSafariboolean

Specifies if the notification should target Safari only. Defaults to true. If set to true, all other platforms are disabled unless explicitly enabled

isWP_WNSboolean

Specifies if the notification should target Windows apps only. Defaults to true. If set to true, all other platforms are disabled unless explicitly enabled

isAdmboolean

Specifies if the notification should target Amazon devices only. Defaults to true. If set to true, all other platforms are disabled unless explicitly enabled

send_afterstring

Schedule delivery for a future date/time (in UTC). The format must be valid per the ISO 8601 standard and compatible with JavaScript’s Date() parser. Example: 2025-09-24T14:00:00-07:00

delayed_optionstring

Controls how messages are delivered on a per-user basis: 'timezone' — Sends at the same local time across time zones. 'last-active' — Delivers based on each user’s most recent session. Not compatible with Push Throttling. If enabled, set throttle_rate_per_minute to 0.

delivery_time_of_daystring

Use with delayed_option: 'timezone' to set a consistent local delivery time. Accepted formats: '9:00AM' (12-hour), '21:45' (24-hour), '09:45:30' (HH:mm:ss).

throttle_rate_per_minutenumber

Overrides the throttle limit set in the OneSignal dashboard settings. Must be enabled through the dashboard. Only available with push notifications. See Push Throttling. If throttle_rate_per_minute is set to 0, then the message will be sent immediately without any rate limiting.

enable_frequency_capboolean

Overrides the frequency cap set in the OneSignal dashboard settings. Must be enabled through the dashboard first. Only available with push notifications. See Frequency Capping. Set to false to disable frequency capping.

idempotency_keystring

A unique identifier used to prevent duplicate messages from repeat API calls. See Idempotent notification requests. Any RFC 9562 UUID supported. Valid for 30 days. Previously called external_id.

Response

200

OR

Example response

{
  "errors": {
    "invalid_aliases": {
      "external_id": [
        "[\"user_id_1\", \"user_id_1\", \"user_id_2\"]"
      ],
      "onesignal_id": [
        "[\"1589641e-bed1-4325-bce4-d2234e578884\", \"1589641e-bed1-4325-bce4-d2234e578884\", \"1589641e-bed1-4325-bce4-d2234e578884\"]"
      ]
    }
  }
}