---
title: "Push notification"
method: POST
path: "/notifications?c=push"
---

# Push notification

`POST /notifications?c=push`

Send a message using the push notification channel.

## Headers

- `Authorization` string, required

## Request body

- object
  - `app_id` string, required — Your OneSignal App ID in UUID v4 format. See [Keys & IDs](/docs/en/keys-and-ids).
  - `include_aliases` object — Target up to 20,000 users by their `external_id`, `onesignal_id`, or your own custom alias. Use with `target_channel` to control the delivery channel. Not compatible with any other targeting parameters like `filters`, `include_subscription_ids`, `included_segments`, or `excluded_segments`. See [Sending messages with the OneSignal API](/reference/create-message#include-aliases).
    - `external_id` string[] — An array of external IDs which should be the same as the user ID in your app. This is the recommended method for targeting users. See [Users](/docs/users).
  - `target_channel` 'push' | 'email' | 'sms' — The targeted delivery channel. Required when using `include_aliases`. Accepts `push`, `email`, or `sms`.
  - `include_subscription_ids` string[] — Target users' specific [subscriptions](/docs/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](/reference/create-message).
  - `included_segments` string[] — Target predefined [Segments](/docs/segmentation). 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](/reference/create-message).
  - `excluded_segments` string[] — Exclude users in predefined [Segments](/docs/segmentation). 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](/reference/create-message).
  - `filters` union[] — Filters define the segment based on user properties like tags, activity, or location using flexible AND/OR logic. Limited to 200 total entries, including fields and `OR` operators. See [Sending messages with the OneSignal API](/reference/create-message#filters).
    - union
      - object — Required. The fitler object.
        - `field` 'tag' | 'last_session' | 'first_session' | 'session_count' | 'session_time' | 'language' | 'app_version' | 'location' | 'country', required — The name of the filter to use.
        - `relation` '=' | '!=' | '>' | '<' | 'exists' | 'not_exists' | 'in_array' | 'not_in_array' | 'time_elapsed_gt' | 'time_elapsed_lt', required — Used with most filters. See details on the specific filter.
        - `key` string — Used with the `tag` filter. This is the tag `key`.
        - `value` string — The value of the `field` or tag `key` in which you want to filter with.
      - object
        - `operator` 'AND' | 'OR' — Chain filter conditions with implicit `AND` and `OR` logic. Never end your `filters` object with an `operator`. See [filters](/reference/create-message#filters) for more.
  - `contents` object, required — The main message body with [language-specific values](/docs/en/multi-language-messaging#supported-languages). Supports [Message Personalization](/docs/message-personalization).
    - `en` string, required — The required message language type. See [Supported Languages](/docs/en/multi-language-messaging#supported-languages).
  - `headings` object — The message title with [language-specific values](/docs/en/multi-language-messaging#supported-languages). Required for Huawei and Web Push. If not set for Web Push, it defaults to your 'Site Name'. Not required if using `template_id` or `content_available`. Supports [Message Personalization](/docs/message-personalization) and must include the same languages as `contents` to ensure localization consistency.
    - `en` string — The title in English. If used, must include the same languages as `contents`.
  - `subtitle` object — iOS only. The subtitle with [language-specific values](/docs/en/multi-language-messaging#supported-languages). Supports [Message Personalization](/docs/message-personalization) and must include the same languages as `contents` to ensure localization consistency.
    - `en` string — The subtitle for iOS push only. If used, must include the same languages as `contents`.
  - `name` string — An internal name you set to help organize and track messages. Not shown to recipients. Maximum 128 characters.
  - `template_id` string — The template ID in UUID v4 format set for the message if applicable. See [Templates](/docs/en/templates).
  - `custom_data` object — Include user or context-specific data (e.g., cart items, OTPs, links) in a message. Use with `template_id`. See [Message Personalization](/docs/message-personalization). Max size: 2KB (Push/SMS), 10KB (Email).
  - `ios_attachments` object — The local name or URL of the media attachment to include in your notification. Users can expand the notification to view images, videos, or other supported attachments. See [Images & Rich Media](/docs/rich-media).
    - `id` string — The URL of the media to display in the notification. Example: `https://avatars.githubusercontent.com/u/11823027?s=200&v=4`
  - `big_picture` string — 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](/docs/rich-media).
  - `huawei_big_picture` string — 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](/docs/rich-media).
  - `adm_big_picture` string — 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](/docs/rich-media).
  - `chrome_web_image` string — 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](/docs/rich-media).
  - `small_icon` string — The local name of the small icon to display in the Google Android notification. See [Notification icons](/docs/notification-icons).
  - `huawei_small_icon` string — The local name of the small icon to display in the Huawei Android notification. See [Notification icons](/docs/notification-icons).
  - `adm_small_icon` string — The local name of the small icon to display in the Amazon Android notification. See [Notification icons](/docs/notification-icons).
  - `large_icon` string — The local name or URL of the large icon to display in the Google Android notification. See [Notification icons](/docs/notification-icons).
  - `huawei_large_icon` string — The local name or URL of the large icon to display in the Huawei Android notification. See [Notification icons](/docs/notification-icons).
  - `adm_large_icon` string — The local name or URL of the large icon to display in the Amazon Android notification. See [Notification icons](/docs/notification-icons).
  - `chrome_web_icon` string — The URL of the icon to display in the Chrome web notification. Defaults to the resource set in the OneSignal dashboard. See [Notification icons](/docs/notification-icons).
  - `firefox_icon` string — The URL of the icon to display in the Firefox web notification. Defaults to the resource set in the OneSignal dashboard. See [Notification icons](/docs/notification-icons).
  - `chrome_web_badge` string — The URL of the icon to display in the Android notification tray for Chrome web notifications. Defaults to the Chrome icon. See [Push](/docs/push#badges).
  - `android_channel_id` string — The UUID of the [Android notification channel category](/docs/android-notification-categories) created within your OneSignal app.
  - `existing_android_channel_id` string — The UUID of the [Android notification channel category](/docs/android-notification-categories) created within your Android app.
  - `huawei_channel_id` string — The UUID of the [Android notification channel category](/docs/android-notification-categories) created within your OneSignal app.
  - `huawei_existing_channel_id` string — The UUID of the [Android notification channel category](/docs/android-notification-categories) 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](https://developer.huawei.com/consumer/cn/doc/HMSCore-Guides/message-classification-0000001149358835#section1653845862216). Subject to daily send limitations ranging from 2 to 5, depending on the specific [third-level classifications](https://developer.huawei.com/consumer/cn/doc/development/HMSCore-Guides/message-restriction-description-0000001361648361#section199311418515) 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](/docs/confirmed-delivery#huawei) — 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](/docs/confirmed-delivery#huawei). 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](/docs/data-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_tag` string — 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_class` string — 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](/docs/badges#huawei-badges).
  - `huawei_badge_set_num` integer — 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](/docs/badges#huawei-badges).
  - `huawei_badge_add_num` integer — 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](/docs/badges#huawei-badges).
  - `priority` 10 | 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`](https://developer.apple.com/documentation/usernotifications/setting_up_a_remote_notification_server/sending_notification_requests_to_apns) and [FCM `priority`](https://firebase.google.com/docs/cloud-messaging/android/message-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](/docs/ios-focus-modes-and-interruption-levels).
  - `ios_sound` string — The local name of the custom sound file to play when the notification is received instead of the default sound. See [Notification sounds](/docs/notification-sounds).
  - `ios_badgeType` 'None' | 'SetTo' | 'Increase' — Set or increment the badge count on iOS devices. Use with `ios_badgeCount`. See [Badges](/docs/badges).
  - `ios_badgeCount` integer — Use with `ios_badgeType` to determine the numerical change to your app's badge count. See [Badges](/docs/badges).
  - `android_accent_color` string — The ARGB Hex formatted color of the Android small icon background. For Android 8+ use [Android notification channel category](/docs/android-notification-categories) and `android_channel_id`.
  - `huawei_accent_color` string — The ARGB Hex formatted color of the Huawei small icon background. For Android 8+ use [Android notification channel category](/docs/android-notification-categories) and `huawei_channel_id`.
  - `url` string — The `https`URL that opens in the browser when a user interacts with the notification. See [URLs, Links and Deep Links](/docs/links). Supports [Message Personalization](/docs/message-personalization).
  - `app_url` string — 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_url` string — Use with `app_url` if your app and website need different URLs. Accepts URLs with protocol `https://`
  - `target_content_identifier` string — 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](https://developer.apple.com/documentation/foundation/nsuseractivity/3238062-targetcontentidentifier).
  - `buttons` object[] — Add a maximum of 3 Action Buttons to Android and iOS push notifications. See [Action Buttons](/docs/action-buttons).
    - `id` string, required — The ID to reference the button clicked event in your app.
    - `text` string, required — The text to display on the button.
    - `icon` string — The local name of the icon to display on the button.
  - `web_buttons` object[] — Add a maximum of 2 Action Buttons to Chrome web push notifications. See [Action Buttons](/docs/action-buttons).
    - `id` string, required — The ID to reference the button clicked event in your app.
    - `text` string, required — The text to display on the button.
    - `url` string, required — The URL to open when the button is clicked.
  - `thread_id` string — An ID to group notifications on Apple devices. Notifications with the same identifier are organized together in the notification center.
  - `ios_relevance_score` number, 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](/docs/ios-relevance-score)
  - `android_group` string — An ID to group notifications on Google Android devices. Notifications with the same identifier are organized together in the notification center.
  - `adm_group` string — An ID to group notifications on Amazon Android devices. Notifications with the same identifier are organized together in the notification center.
  - `ttl` integer — 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](/docs/push#time-to-live).
  - `collapse_id` string — An ID that replaces older notifications with newer ones that have the same identifier. For mobile push only. See [Push: Collapse ID](/docs/push#collapse-id).
  - `web_push_topic` string — An ID that prevents replacement of older notifications with newer ones that have different identifiers. For web push only. See [Push: Web Push Topic](/docs/push#web-push-topic).
  - `data` object — Bundle a custom data map within your notification, which is then passed to your app. See [Push: Additional Data](/docs/push#additional-data).
  - `content_available` boolean — 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](/docs/data-notifications).
  - `ios_category` string — Enable users to respond directly to a notification without launching the app. The [Category](https://developer.apple.com/documentation/usernotifications/unnotificationcategory) will activate the corresponding [Notification Content Extension](https://developer.apple.com/documentation/usernotificationsui/unnotificationcontentextension/) in your app when the push is interacted with.
  - `apns_push_type_override` string — Use only for VoIP notifications. Corresponds to the [`apns-push-type`](https://developer.apple.com/documentation/usernotifications/sending-notification-requests-to-apns#Send-a-POST-request-to-APNs). 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.
  - `isIos` boolean — 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.
  - `isAndroid` boolean — 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.
  - `isHuawei` boolean — 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.
  - `isAnyWeb` boolean — Specifies if the notification should target web push only. Defaults to `true`. If set to `true`, all other platforms are disabled unless explicitly enabled.
  - `isChromeWeb` boolean — Specifies if the notification should target Chrome only. Defaults to `true`. If set to `true`, all other platforms are disabled unless explicitly enabled.
  - `isFirefox` boolean — Specifies if the notification should target Firefox only. Defaults to `true`. If set to `true`, all other platforms are disabled unless explicitly enabled.
  - `isSafari` boolean — Specifies if the notification should target Safari only. Defaults to `true`. If set to `true`, all other platforms are disabled unless explicitly enabled
  - `isWP_WNS` boolean — Specifies if the notification should target Windows apps only. Defaults to `true`. If set to `true`, all other platforms are disabled unless explicitly enabled
  - `isAdm` boolean — 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_after` string — Schedule delivery for a future date/time (in UTC). The format must be valid per the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard and compatible with [`JavaScript’s Date() parser`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/Date#datestring). Example: `2025-09-24T14:00:00-07:00`
  - `delayed_option` string — 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](/docs/throttling). If enabled, set `throttle_rate_per_minute` to `0`.
  - `delivery_time_of_day` string — 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_minute` number — Overrides the throttle limit set in the OneSignal dashboard settings. Must be enabled through the dashboard. Only available with push notifications. See [Push Throttling](/docs/throttling). If `throttle_rate_per_minute` is set to `0`, then the message will be sent immediately without any rate limiting.
  - `enable_frequency_cap` boolean — 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](/docs/frequency-capping). Set to `false` to disable frequency capping.
  - `idempotency_key` string — A unique identifier used to prevent duplicate messages from repeat API calls. See [Idempotent notification requests](/reference/idempotent-notification-requests). Any RFC 9562 UUID supported. Valid for 30 days. Previously called `external_id`.

## Response `200`

200

- union — Two variants are possible with HTTP 200, distinguished by the `id` field: a UUID indicates the message was accepted and dispatched (Message Sent); an empty string indicates the request was valid but no subscribers matched (Message Not Sent). Inspect `errors` when `id` is empty.
  - object — Notification was accepted and dispatched to one or more subscribers. `errors` (when present) reports per-channel invalid identifiers; `warnings` (when present) reports non-fatal issues such as unsubscribed external IDs. `external_id` echoes the request's `idempotency_key` (or null when not provided).
    - `id` string, uuid, required — Notification ID in UUID v4 format. If `id` is an empty string, then the message was not sent.
    - `external_id` string, nullable — The `idempotency_key` parameter from the request, echoed back. Null when no idempotency_key was provided. Used to detect duplicate-send attempts — see [Idempotent message requests](/reference/idempotent-notification-requests).
    - `errors` object — Per-channel listings of invalid identifiers in the request. Only emitted when at least one identifier in the request failed validation. Each listed key is optional; the keys present depend on the channel and request.
      - `invalid_aliases` object — The alias label that was used in the `include_aliases` parameter.
        - `external_id` string[]
        - `onesignal_id` string[]
      - `invalid_player_ids` string[]
    - `warnings` union — Non-fatal warnings emitted alongside a successful send.
      - object — Object form.
        - `invalid_external_user_ids` string — external_ids whose subscriptions are unsubscribed.
      - string[] — Array form. Contains non-fatal warning messages.
  - object — Validation passed but the targeting matched zero subscribers (and the notification is not lightspeed-eligible). HTTP status is 200 even though no message was dispatched. `id` is always the empty string in this branch — use it as the discriminator from the Message Sent variant.
    - `id` '', required — If the message `id` is an empty string, then no message was sent. The request appears to be formatted correctly, but there are issues with the aliases, segments, or filters targeted.
    - `errors` string[], required — Reasons the message was not dispatched. The most common value is `"All included players are not subscribed"`, which means every subscription matched by the segments/aliases/filters was unsubscribed before send time. Per-channel sentinels (e.g., invalid identifiers) may also appear.
    - `warnings` union — Non-fatal warnings emitted alongside a successful send.
      - object — Object form.
        - `invalid_external_user_ids` string — external_ids whose subscriptions are unsubscribed.
      - string[] — Array form. Contains non-fatal warning messages.

## Other responses

- `400` — 400
- `403` — Forbidden. The Authorization key cannot send notifications for this app, or the request targets a feature the app's plan does not enable.
- `429` — Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.
- `503` — Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.

---

[API](https://skmtc.net/onesignal/apis/api-onesignal-com.md) · [All operations](https://skmtc.net/onesignal/apis/api-onesignal-com/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/onesignal/api-onesignal-com/versions/0fc223f7e338/schema)