POST
/
notifications?c=push
Push notification
curl --request POST \
  --url 'https://api.onesignal.com/notifications?c=push' \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '{
  "app_id": "YOUR_APP_ID",
  "include_aliases": {
    "external_id": [
      "<string>"
    ]
  },
  "target_channel": "push",
  "include_subscription_ids": [
    "<string>"
  ],
  "included_segments": [
    "<string>"
  ],
  "excluded_segments": [
    "<string>"
  ],
  "filters": [
    {
      "field": "tag",
      "relation": "=",
      "key": "<string>",
      "value": "<string>"
    }
  ],
  "contents": {
    "en": "Default message."
  },
  "headings": {
    "en": "<string>"
  },
  "subtitle": {
    "en": "<string>"
  },
  "name": "<string>",
  "template_id": "<string>",
  "custom_data": {},
  "ios_attachments": {
    "id": "<string>"
  },
  "big_picture": "<string>",
  "huawei_big_picture": "<string>",
  "adm_big_picture": "<string>",
  "chrome_web_image": "<string>",
  "small_icon": "<string>",
  "huawei_small_icon": "<string>",
  "adm_small_icon": "<string>",
  "large_icon": "<string>",
  "huawei_large_icon": "<string>",
  "adm_large_icon": "<string>",
  "chrome_web_icon": "<string>",
  "firefox_icon": "<string>",
  "chrome_web_badge": "<string>",
  "android_channel_id": "<string>",
  "existing_android_channel_id": "<string>",
  "huawei_channel_id": "<string>",
  "huawei_existing_channel_id": "<string>",
  "huawei_category": "MARKETING",
  "huawei_msg_type": "message",
  "huawei_bi_tag": "<string>",
  "priority": 10,
  "ios_interruption_level": "active",
  "ios_sound": "<string>",
  "ios_badgeType": "None",
  "ios_badgeCount": 123,
  "android_accent_color": "<string>",
  "huawei_accent_color": "<string>",
  "url": "<string>",
  "app_url": "<string>",
  "web_url": "<string>",
  "target_content_identifier": "<string>",
  "buttons": [
    {
      "id": "<string>",
      "text": "<string>",
      "icon": "<string>"
    }
  ],
  "web_buttons": [
    {
      "id": "<string>",
      "text": "<string>",
      "url": "<string>"
    }
  ],
  "thread_id": "<string>",
  "ios_relevance_score": 123,
  "android_group": "<string>",
  "adm_group": "<string>",
  "ttl": 259200,
  "collapse_id": "<string>",
  "web_push_topic": "<string>",
  "data": {},
  "content_available": true,
  "ios_category": "<string>",
  "apns_push_type_override": "<string>",
  "isIos": true,
  "isAndroid": true,
  "isHuawei": true,
  "isAnyWeb": true,
  "isChromeWeb": true,
  "isFirefox": true,
  "isSafari": true,
  "isWP_WNS": true,
  "isAdm": true,
  "send_after": "<string>",
  "delayed_option": "<string>",
  "delivery_time_of_day": "<string>",
  "throttle_rate_per_minute": 123,
  "enable_frequency_cap": true,
  "idempotency_key": "<string>"
}'
{
  "id": "<string>",
  "external_id": "<string>",
  "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\"]"
      ]
    },
    "invalid_player_ids": [
      "<string>"
    ]
  }
}

​
Overview

The Create message API allows you to send push notifications, emails, and SMS to your users. This guide is specific for push. See Email or SMS to send to those channels. Ensure your application is properly configured by following the Mobile SDK Setup and/or Web SDK Setup guides. You should see subscribed push Subscriptions in your OneSignal dashboard to send them messages.
Review the Sending messages with the OneSignal API guide for details on how to structure your messages.

Headers

​
Authorization
string
default:Key YOUR_APP_API_KEY
required

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

Body

application/json
​
app_id
string
default:YOUR_APP_ID
required

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

​
contents
object
required

The main message body with language-specific values. Supports Message Personalization.

​
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.

​
target_channel
enum<string>
default:push

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

Available options:
push,
email,
sms
​
include_subscription_ids
string[]

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_segments
string[]

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_segments
string[]

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.

​
filters
(Filter · object | Operator · object)[]

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.

Required array length: 1 - 200 elements
​
headings
object

The message title with language-specific values. 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 and must include the same languages as contents to ensure localization consistency.

​
subtitle
object

iOS only. The subtitle with language-specific values. Supports Message Personalization and must include the same languages as contents to ensure localization consistency.

​
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.

​
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. 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.

​
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.

​
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.

​
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.

​
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.

​
small_icon
string

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

​
huawei_small_icon
string

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

​
adm_small_icon
string

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

​
large_icon
string

The local name or URL of the large icon to display in the Google Android notification. See 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.

​
adm_large_icon
string

The local name or URL of the large icon to display in the Amazon Android notification. See 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.

​
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.

​
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.

​
android_channel_id
string

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

​
existing_android_channel_id
string

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

​
huawei_channel_id
string

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

​
huawei_existing_channel_id
string

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

​
huawei_category
enum<string>
default:MARKETING

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.

Available options:
MARKETING,
IM,
VOIP,
SUBSCRIPTION,
TRAVEL,
HEALTH,
WORK,
ACCOUNT,
EXPRESS,
FINANCE,
DEVICE_REMINDER,
MAIL
​
huawei_msg_type
enum<string>
default:message

The type of notification being sent to Huawei devices. Options: message - (default) For displayable notifications to the user. Notification will be shown even if the app is force quit. If the device is offline it will display the notification when it connects to the internet within the ttl timeframe (usually 3 days). Does not support Confirmed Delivery, Huawei requires using their dashboard to track this. data - used for notifications containing data payloads you intend to process in the background. If the app is force quit, HMS Core will not start the app to process the notification. Supports Confirmed Delivery.

Available options:
message,
data
​
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.

​
priority
enum<integer>
default:10

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.

Available options:
10,
5
​
ios_interruption_level
enum<string>
default:active

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.

Available options:
active,
passive,
time_sensitive,
critical
​
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.

​
ios_badgeType
enum<string>
default:None

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

Available options:
None,
SetTo,
Increase
​
ios_badgeCount
integer

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

​
android_accent_color
string

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_color
string

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

​
url
string

The httpsURL that opens in the browser when a user interacts with the notification. See URLs, Links and Deep Links. Supports 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.

​
buttons
object[]

Add a maximum of 3 Action Buttons to Android and iOS push notifications. See Action Buttons.

Maximum length: 3
​
web_buttons
object[]

Add a maximum of 2 Action Buttons to Chrome web push notifications. See Action Buttons.

Maximum length: 2
​
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

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_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
default:259200

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_id
string

An ID that replaces older notifications with newer ones that have the same identifier. For mobile push only. See 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.

​
data
object

Bundle a custom data map within your notification, which is then passed to your app. See 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.

​
ios_category
string

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_override
string

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.

​
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 standard and compatible with JavaScript’s Date() parser. 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. 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. 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. 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. Must be a v3 or v4 UUID. Valid for 30 days. Previously called external_id.

Response

200

​
id
string

The message ID in UUID v4 format. If id is an empty string, then the message was not sent.

​
external_id
string

The idempotency_key parameter if set. Used to prevent duplicate messages from repeat API calls. See Idempotent message requests.

​
errors
object

If the message id is set, then a message was sent. Any errors reported are with individual Users or Subscriptions that cannot be sent the message.