Send a message using the push notification channel.
Overview
The Create Notification API allows you to send push notifications to your subscribers.
How to use this API
To get started with this API, ensure your application is properly configured by following the Mobile SDK Setup and Web SDK Setup guides.
Craft your message
Draft the message and embed it in the contents
parameter.
English is required; all other target languages are optional for localized push notifications.
Refer to Push Notification Content for additional configuration parameters.
Choose a targeting strategy
Choose only one strategy for targeting users with this message:
- Segments
- Filters
- Aliases
Schedule delivery
You can specify rate limits and delivery timing as well. See Delivery Notification Parameters to learn more.
Examples
Send to segments
curl --include \
--request POST \
--header "Content-Type: application/json; charset=utf-8" \
--header "Authorization: Basic <YOUR_REST_API_KEY>" \
--data-binary "{
\"app_id\": \"YOUR_APP_ID\",
\"contents\": {\"en\": \"English Message\"},
\"included_segments\": [\"Subscribed Users\"]
}" \
https://api.onesignal.com/notifications
Send to dynamically filtered segment
curl --include \
--request POST \
--header "Content-Type: application/json; charset=utf-8" \
--header "Authorization: Basic <YOUR_REST_API_KEY>" \
--data-binary "{
\"app_id\": \"YOUR_APP_ID\",
\"contents\": {\"en\": \"English Message\"},
\"headings\": {\"en\": \"English Title\"},
\"target_channel\": \"push\",
\"filters\": [
{\"field\": \"tag\", \"key\": \"level\", \"relation\": \">\", \"value\": \"10\"},
{\"operator\": \"OR\"},
{\"field\": \"amount_spent\", \"relation\": \">\", \"value\": \"0\"}
]
}" \
https://api.onesignal.com/notifications
Send to specific users via External ID
curl --include \
--request POST \
--header "Content-Type: application/json; charset=utf-8" \
--header "Authorization: Basic <YOUR_REST_API_KEY>" \
--data-binary "{
\"app_id\": \"YOUR_APP_ID\",
\"contents\": {\"en\": \"English Message\"},
\"headings\": {\"en\": \"English Title\"},
\"target_channel\": \"push\",
\"include_aliases\": {
\"external_id\": [
\"CUSTOM-EXTERNAL_ID-ASSIGNED-BY-YOU-1\",
\"CUSTOM-EXTERNAL_ID-ASSIGNED-BY-YOU-2\",
\"CUSTOM-EXTERNAL_ID-ASSIGNED-BY-YOU-3\"
]
}
}" \
https://api.onesignal.com/notifications
Send to specific subscriptions
curl --include \
--request POST \
--header "Content-Type: application/json; charset=utf-8" \
--header "Authorization: Basic <YOUR_REST_API_KEY>" \
--data-binary "{
\"app_id\": \"YOU_APP_ID\",
\"name\": {\"en\": \"My notification Name\"},
\"contents\": {\"en\": \"English Message\"},
\"headings\": {\"en\": \"English Title\"},
\"include_subscription_ids\": [
\"SUBSCRIPTION_ID_1\",
\"SUBSCRIPTION_ID_2\",
\"SUBSCRIPTION_ID_3\"
]
}" \
https://api.onesignal.com/notifications
Body Parameters
Push Notification Content
Tailor the presentation of notifications across various push platforms. The collective impact of these parameters is significant, as they work together to enhance the effectiveness of push campaigns and ensure that users receive the most appropriate and engaging content, ultimately leading to higher user engagement and satisfaction.
Template & text content properties (click to expand)
contents
contents
Type object
Platforms All
Description
The message to display in the main body of the notification. This field support Message Personalization.
Required when
content_available
isfalse
- Or
template_id
isn't set
The object consists of key-value pairs where each key is a language code string (e.g., "en" for English, "es" for Spanish), and the value is the localized message intended for speakers of that language.
- English localization must be included in the mapping to ensure broad accessibility.
- Ensure keys align with those defined in the
headings
property for localization consistency.
Example
{
"contents": {
"en": "English Message",
"es": "Spanish Message"
}
}
headings
headings
Type object
Platforms All
Description
Specifies the notification's title using a map of language codes to the corresponding title text for each language. This field support Message Personalization.
- Required for Huawei devices.
- A title is required for Web Push Notifications. If not provided, defaults to the "Site Name" specified in Settings in the Dashboard.
- This parameter is set the same as
contents
; please see its documentation for more information. - Language codes must be mirrored in the
contents
parameter to ensure a unified experience across the notification's title and body.
Example
{
"headings": {
"en": "English Title",
"es": "Spanish Title"
}
}
subtitle
subtitle
Type object
Platforms iOS
Description
Defines the subtitle of the notification. This parameter enriches the notification's content by providing additional context or information beneath the main title.
- Behaves the same as
contents
; please see its documentation for more information. - Language codes must be mirrored in the
contents
andheadings
parameters to ensure a unified experience across the notification's title and body.
Example
{
"subtitle": {
"en": "English Subtitle",
"es": "Spanish Subtitle"
}
}
template_id
template_id
Type string
Platforms All
Description
Identifies a specific template configured within the dashboard. Leveraging templates facilitates standardized notifications across different campaigns, allowing for a cohesive customer experience and analytics to be aggregated at the template level, which can be viewed on the dashboard. See Templates for details.
Provide the UUID of the template, which can be found in the URL when viewing a template on our dashboard.
Example
{
"template_id": "be4a8044-bbd6-11e4-a581-000c2940e62c"
}
Image & icon properties (click to expand)
ios_attachments
ios_attachments
Type object
Platforms iOS
Description
Include local and remote content in your notifications to improve visuals. Make your notifications stand out by allowing users to view images, videos, and other supported media directly within the notification by tapping and holding it.
- Refer to Images & Rich Media for details on adding multimedia to a notification.
- Provide JSON where each key-value pair consists of:
- Custom media ID (key)
- Valid local resource name or URL (value) pointing to media to be attached
- Setting
mutable_content
is unnecessary for downloading attachments; the OneSignal iOS SDK does this automatically.
Example
{
"bg": "https://store.onesignal.com/assets/offers/bg_vip_offer.jpg",
"offerHero": "https://store.onesignal.com/offers/vip-offer-2/hero.jpg"
}
big_picture
big_picture
Type string
Platforms Android
Description
Specify an image to display in the expanded notification view on Android devices. Acceptable values are named drawable resources within your app or the URL of an image. Including a large image, or "big picture," can enhance the notification's visual impact, making it more engaging.
- For local drawable resources, provide the image's resource name within your app's project.
- When using remote images, ensure the URL points to a reliable and accessible image resource that conforms to the required dimensions and file size.
Example
{
"big_picture": "https://store.onesignal.com/offers/vip-offer-2/hero.jpg"`
}
chrome_web_image
chrome_web_image
Type string
Platforms Web push
Description
Specify an image to display in the notification on the Chrome web browser for Windows and Android. Chrome does not support this parameter for macOS and instead expands the chrome_web_icon
instead. See Web push setup for details.
Example
{
"chrome_web_image": "https://domain.com/large-image.jpg"
}
huawei_big_picture
huawei_big_picture
Type string
Platforms Huawei
Description
Serves the same purpose as big_picture
for Huawei devices.
Example
{
"huawei_big_picture": "https://store.onesignal.com/offers/vip-offer-2/hero.jpg"`
}
adm_big_picture
adm_big_picture
Type string
Platforms Amazon
Description
Serves the same purpose as big_picture
for Amazon devices.
Example
{
"adm_big_picture": "https://store.onesignal.com/offers/vip-offer-2/hero.jpg"`
}
chrome_big_picture
chrome_big_picture
Type string
Platforms Chrome Apps
Description
Serves the same purpose as big_picture
for Chrome Apps.
Example
{
"chrome_big_picture": "https://store.onesignal.com/offers/vip-offer-2/hero.jpg"`
}
small_icon
small_icon
Type string
Platforms Android
Description
Specify the icon to display in the status bar and the top-left corner of the notification. Customizing the small icon helps maintain brand consistency and improves the user's ability to recognize your app's notifications at a glance.
- Provide the icon resource name (without its file extension). The SDK will reference this name to fetch the appropriate icon from your app's resources.
- If not specified, Android defaults to using a bell icon or
ic_stat_onesignal_default
if defined in your app. - See Notification icons for details.
Example
Set the custom icon to an app resource named "your_notification_icon"
.
{
"small_icon": "your_notification_icon"
}
huawei_small_icon
huawei_small_icon
Type string
Platforms Huawei
Description
Functionally equivalent to small_icon.
Example
{
"huawei_small_icon": "your_notification_icon"
}
large_icon
large_icon
Type string
Platforms Android
Description
Specify the large icon within the notification content area, distinct from the smaller status bar icon for the notification. See Notification icons for details.
If using a drawable resource, provide the name without the file extension. The SDK will load for this resource from your app's resource directories.
- Alternatively, you can specify a URL to use an image from the web.
- If not set, the notification will display the standard large icon defined in the app's notification template or the Android system default.
Example
Use a custom resource named "your_large_icon"
stored in the app's drawable resources.
{
"large_icon": "your_large_icon"
}
huawei_large_icon
huawei_large_icon
Type string
Platforms Huawei
Description
Functionally equivalent to large_icon.
Example
{
"huawei_large_icon": "your_large_icon"
}
adm_small_icon
adm_small_icon
Type string
Platforms Amazon
Description
Functionally equivalent to small_icon.
Example
{
"adm_small_icon": "your_notification_icon"
}
adm_large_icon
adm_large_icon
Type string
Platforms Huawei
Description
Functionally equivalent to large_icon.
Example
{
"adm_large_icon": "your_large_icon"
}
chrome_web_icon
chrome_web_icon
Type string
Platforms Chrome web push
Description
Defines the icon to be used in web push notifications on the Chrome browser to ensure that Chrome notifications are visually consistent with your brand or message.
- Provide a URL to the image you want as the notification icon.
- The image must be accessible over the web.
- Although common image types are supported, GIFs will not animate. For optimal display across various devices, especially those with high DPI screens, it is recommended to use an image size of 256x256 pixels, with the minimum size being 80x80 pixels.
Example
{
"chrome_web_icon": "https://domain.com/assets/icon.png"
}
chrome_web_image
chrome_web_image
Type string
Platforms Chrome web push. Windows and Android only.
Description
Specify the image thumbnail for image-type notifications. This feature works exclusively on Chrome for Windows and Android. Chrome web push notifications on macOS will continue to use the image specified by chrome_web_icon
instead.
Provide a URL to the image to display. The image must be web-accessible and optimized for quick loading. See Web push setup for details.
Example
{
"chrome_web_image": "https://domain.com/path/to/large-image.png"
}
chrome_web_badge
chrome_web_badge
Type string
Platforms Chrome web push. Android only.
Description
Specify the icon to be displayed for web push notifications in the Notification Shade on Android devices using Chrome. The badge icon is a more miniature graphic, typically used to represent the app or website minimally within the system's notification area.
Provide a URL pointing to the image for the badge icon. Ensure the image is web-accessible and optimized for small sizes for clarity. See Web push setup for details.
Example
{
"chrome_web_badge": "https://domain.com/path/to/badge-icon.png"
}
firefox_icon
firefox_icon
Type string
Platforms Firefox web push
Description
Functionally equivalent to chrome_web_icon
.
Example
{
"firefox_icon": "your_notification_icon"
}
chrome_icon
chrome_icon
Type string
Platforms Chrome app
Description
Specify the icon, separate from the app icon, for notifications targeting Chrome Apps.
Provide the local path to the icon within the Chrome App's directory structure. The app icon gets used by default if this value isn't given.
Example
{
"chrome_icon": "path/to/your/icon.png"
}
Channels, sound, badges, & custom display properties(click to expand)
android_channel_id
android_channel_id
Type string
Platforms Android
Description
When targeting Android Oreo (8.0+) or later devices, deliver notifications through a notification channel.
- See Android: Notification Channel Categories.
- Must be unique per package.
- Use the Channel ID from the notification channel configured in the app Dashboard.
Example
{
"android_channel_id": "your-channel-uuid"
}
existing_android_channel_id
existing_android_channel_id
Type string
Platforms Android
Description
Functionally equivalent to android_channel_id
, except you may specify a notification channel created outside the OneSignal Dashboard. Refer to the Android documentation on creating notification channels and obtaining their IDs to ensure correct implementation and usage within your notification strategy.
Example
{
"existing_android_channel_id": "your-predefined-channel-id"
}
huawei_channel_id
huawei_channel_id
Type string
Platforms Huawei
Description
Functionally equivalent to android_channel_id
.
Example
{
"huawei_channel_id": "your-channel-uuid"
}
huawei_existing_channel_id
huawei_existing_channel_id
Type string
Platforms Huawei
Description
Functionally equivalent to existing_android_channel_id
.
Example
{
"huawei_existing_channel_id": "your-predefined-channel-id"
}
priority
priority
Type number
Platforms iOS, Android, Chrome web push
Description
Determines the delivery priority of notifications through push servers such as Apple Push Notification Service (APNS) or Firebase Cloud Messaging (FCM). It influences how quickly a notification is delivered to the device, impacting its processing, especially in power-saving modes.
- The value of
10
assigns high priority to the notification; default for iOS. - Values other than
10
set the notification to normal priority, ensuring that notifications don't unnecessarily disrupt the user or consume excessive power; default for Android.
Example
{
"priority": 5
}
ios_interruption_level
ios_interruption_level
Type string
Platforms iOS 15+
Description
Specify the priority and delivery timing of notifications based on their importance and the urgency with which they should interrupt the user. It aligns with Apple's expanded notification management system, which includes focus modes and various interruption levels.
active
– The default for standard notifications that do not require immediate attention.passive
– For notifications that should not alert the user or wake the device.time_sensitive
– For non-critical notifications that should be delivered promptly.critical
– For notifications that demand immediate attention due to their critical nature. Always presented to the user even when Do Not Disturb is active and thus requires a special entitlement.
Example
{
"ios_interruption_level": "critical"
}
ios_sound
ios_sound
Type string
Platforms iOS
Description
Specify a custom sound file to play when the notification is received instead of the default sound.
- Provide the name of the sound file included in your app bundle.
- Pass
"nil"
if you want to deliver the notification silently without sound or vibration. - Ensure the sound file (e.g.,
'.wav'
) is supported by iOS for notification sounds and is correctly bundled with your app.
Example
{
"ios_sound": "notification.wav"
}
wp_wns_sound
wp_wns_sound
Type string
Platforms Windows app
Description
Functionally equivalent to ios_sound
.
The sound file should be properly bundled with your Windows app.
Example
{
"wp_wns_sound": "notification.wav"
}
ios_badgeType
ios_badgeType
Type string
Platforms iOS
Description
Specify how the notification affects the badge count displayed on your app's icon. Use with associated parameter, ios_badgeCount
, to update the app's badge number based on the specified action.
"None"
: The badge count remains unchanged. Use when you want to send a notification without affecting the badge indicator."SetTo"
: Set the badge count to the exact number provided, overriding the current count."Increase"
: The value specified inios_badgeCount
is added to the current badge count; negative numbers will decrease the badge count.
Example
Set badge count to 5.
{
"ios_badgeType": "SetTo",
"ios_badgeCount": 5
}
Decrease badge count by 1.
{
"ios_badgeType": "Increase",
"ios_badgeCount": -1
}
ios_badgeCount
ios_badgeCount
Type number
Platforms iOS
Description
Works with ios_badgeType
to determine the numerical change to your app's badge count.
The provided value must be a whole number.
Example
{
"ios_badgeType": "SetTo",
"ios_badgeCount": 5
}
android_accent_color
android_accent_color
Type string
Platforms Android 5+
Description
Set the background color of the notification circle to the left of the notification text. This parameter applies only to apps targeting Android API level 21 or higher.
Specify the color using ARGB Hex format.
Example
{
"android_accent_color": "FFFF0000"
}
huawei_accent_color
huawei_accent_color
Type string
Platforms Huawei
Description
Functionally equivalent to android_accent_color
.
Example
{
"huawei_accent_color": "FFFF0000"
}
apns_alert
apns_alert
Type object
Platforms iOS 10+
Description
It enables you to localize push notifications.
- The APNS Alert object should include the
loc-key
andloc-args
properties. - Localization keys should correspond to the localized text in your app's Localizable.strings file. The device will display the localized string that matches the user's language settings.
- For other APNS Alert parameters, refer to Apple's documentation.
Example
{
"apns_alert": {
"loc-key": "GAME_PLAY_REQUEST_FORMAT",
"loc-args": ["Jenna", "Frank"]
}
}
The key"GAME_PLAY_REQUEST_FORMAT"
is a key defined in a Localizable.strings file whose value is "%@ and %@ request play"
. The arguments "Jenna"
and "Frank"
replace the format specifiers in the string, producing the message "Jenna and Frank request play"
.
URLs, click actions, & button properties (click to expand)
url
url
Type string
Platforms All
Description
The URL that opens in the browser when a user interacts with the notification.
- Supports Message Personalization, empowering you to dynamically customize URLs.
- For Apple devices, ensure that your URL uses HTTPS or set the
NSAppTransportSecurity
settings in your app's property list to allow non-secure connections. - This parameter can be used to implement Deep Linking.
Example
{
"url": "https://store.onesignal.com?offer={{ message.custom_data.offer_code }}&{{ subscription.external_id }}&{{ first_name | 'Friend' }}"`
}
☝️ provides:
-
An offer code to load and a mechanism to track the performance of the offer -
message.custom_data.offer_code
-
The External ID of the user that can be used for further processing (e.g., updating Data Tags, engagement tracking, etc.) -
subscription.external_id
-
The recipient's first name, if defined in Data Tags, or a default value that can be used to personalize the content on the offer page -
first_name | 'Friend'
app_url
app_url
Type string
Platforms Mobile, desktop
Description
Performs a similar function to the url
parameter but exclusively targets mobile & desktop push platforms like iOS, Android, and ChromeApps. Setting will cause the URL to open within your app.
- Use this with
web_url
if your app and website need different URLs. Otherwise, useurl
. - Direct users to specific content or functions within your app.
- Integrate content on your site with intents in your app to deliver a cohesive user experience across platforms and devices.
Example
{
"app_url": "com.onesignal.storeapp://offerpage?offer={{ message.custom_data.offer_code }}"`
}
☝️ enables:
- Deep-linking into the StoreApp to open the offer page
- The offer code to load -
message.custom_data.offer_code
web_url
web_url
Type string
Platforms Web push
Description
Performs a similar function to the url
parameter but exclusively targets web push platforms like Chrome, Firefox, and Safari. Setting this enables you to segment your notification strategy and ensure that the notification action– opening a URL in the browser –is only applied to web push notifications.
- Use this with
app_url
if your app and website need different URLs. Otherwise, useurl
.
target_content_identifier
target_content_identifier
Type string
Platforms iOS 13+
Description
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. This identifier enables your app to handle notifications more contextually to enhance user engagement by delivering content directly relevant to the current app context or scene. See Apple's documentation for details.
Action Buttons
Allow users to take more than one action on a notification. Learn more about Action Buttons.
buttons
buttons
Type [object]
Platforms Android 4.1+, iOS 8+, Amazon, Huawei
Description
This feature lets you provide clear actions for users to take directly from the notification pane.
- Buttons appear in the notification in the same order as the array
- Each button object must include
id
andtext
properties. - On Android, you can specify
icon
for each button to provide a more tailored experience. Icons should reference drawable resources in your app.
Example
[
{ "id": "first_button", "text": "Share", "icon": "ic_menu_share" },
{ "id": "second_button", "text": "Send", "icon": "ic_menu_send" }
]
web_buttons
web_buttons
Type [object]
Platforms Chrome web push
Description
Add Action Buttons to web push notifications.
- Each action button object must include the
id
andtext
properties. - Include these additional properties to customize appearance and behavior:
icon
- URL of an image to display on the buttonurl
- URL to open when the button is clicked
Example
[
{
"id": "like-button",
"text": "Like",
"icon": "http://i.imgur.com/N8SN8ZS.png",
"url": "https://yoursite.com"
},
{
"id": "read-more-button",
"text": "Read more",
"icon": "http://i.imgur.com/MIxJp1L.png",
"url": "https://yoursite.com"
}
]
icon_type
icon_type
Type string
Platforms iOS
Description
Specify the type of icon used in an Action Button within iOS notifications. You can choose between system-defined and custom icons in your app.
- Acceptable values are:
system
- built-in icons that ensure consistency with iOS design language.custom
- custom icons designed specifically for your app; deliver notifications with a more personalized touch.
Example
{
"icon_type": "system"
}
Grouping & collapsing
Grouping lets you combine multiple notifications into one to improve the user experience, while collapsing lets you dismiss old notifications in favor of newer ones. See Notification Grouping and Remove notifications & TTL for details.
Grouping & collapsing properties (click to expand)
thread_id
thread_id
Type string
Platforms iOS 12+
Description
Organize notifications on Apple devices by grouping related notifications. See Apple's documentation for details.
Assigning the same thread_id
to multiple notifications results in a group. Grouped notifications allow users to interact with multiple notifications from the same thread, resulting in a cleaner notification center.
Example
{
"thread_id": "project_updates"
}
summary_arg
summary_arg
Type string
Platforms iOS 12+
Description
Use in conjunction with thread_id
to specify a name or identifier (such as a person or a topic) for a notification group. See Apple's Documentation for details.
This name appears in the summary for the grouped notifications, giving context to the user about the source or subject of the notification.
Example
Generates the summary, "2 more notifications from Damian", assuming two notifications are in the group.
{
"summary_arg": "Damian"
}
summary_arg_count
summary_arg_count
Type number
Platforms iOS 12+
Description
Works alongside summary_arg
to help manage grouped notifications on Apple devices, allowing you to specify the total number of notifications within a group.
The summary for the grouped notifications dynamically updates itself based on the total count provided.
Example
Assuming the group already contains 12 notifications, update the total notification count to 14.
{
"summary_arg_count": 2
}
ios_relevance_score
ios_relevance_score
Type number
Platforms iOS 15+
Description
Prioritize notifications within a group on iOS devices. Assigning a relevance score to each notification gives you control of the order in which notifications are displayed when grouped, ensuring that the most relevant notifications are prominently displayed. See Apple's documentation for details.
A higher score suggests greater relevance. Notifications with higher scores are displayed first in the group.
Example
{
"ios_relevance_score": 0.8
}
android_group
android_group
Type string
Platforms Android
Description
Group notifications on Android devices. Notifications with the same group identifier are grouped using Android's Notification Grouping feature.
- Organizes multiple notifications into a single group, reducing clutter and improving the user experience.
- Useful for apps that send several notifications quickly, such as messaging apps or news apps.
Example
{
"android_group": "updates"
}
adm_group
adm_group
Type string
Platforms Amazon
Description
Group notifications on Amazon devices. Similar behavior to android_group
parameter.
adm_group_message
adm_group_message
Type object
Platforms Amazon
Description
Configure a summary message for notifications grouped together. Similar behavior to android_group_message
parameter.
Example
{
"adm_group_message": {
"en": "You have $[notif_count] new messages."
}
}
ttl
ttl
Type number
Platforms All
Description
The "Time To Live" (TTL) defines the duration in seconds for which a notification remains valid if the device is offline, ensuring that outdated notifications aren't delivered if the device reconnects after some time. See Remove notifications & TTL for details.
Setting a TTL for time-sensitive information is essential so users don't receive outdated notifications.
- The default TTL is 259,200 seconds (3 days), which balances timely delivery and reasonable wait times for devices to return online.
- You can set a maximum TTL of 2,419,200 seconds (28 days).
Example
{
"ttl": 86400
}
collapse_id
collapse_id
Type string
Platforms Android, iOS
Description
Prevent duplicate notifications by merging notifications with the same identifier into a single one. It helps keep the notification center organized and updates existing notifications without creating new ones.
- Use when the relevance of information can change quickly, like with news or stock updates.
- Using the same
collapse_id
will replace or update the content of an existing notification that uses the same identifier. - The identifier is limited to 64 characters.
- More details in Remove notifications & TTL, Apple's documentation, and Android's documentation.
Example
{
"collapse_id": "update_notification_12345"
}
web_push_topic
web_push_topic
Type string
Platforms Web push
Description
Update the currently visible notification with a new version. If the topic between two notifications is the same, the newest notification will replace the older one. See Remove notifications & TTL for details.
- Inspect a notification's topic in your app and handle it accordingly; handle notifications of different topics independently to alleviate overwriting an existing notification.
- Use topics to segregate notifications into meaningful categories.
Example
{
"web_push_topic": "news_update"
}
Data, background & category properties (click to expand)
data
data
Type object
Platforms All
Description
Bundle a custom data map within your notification, which is then passed back to your app, akin to the Additional Data feature available in the dashboard.
- It supports up to
2048
bytes of data. - Add actionable information or metadata to your notifications.
- Data is available to your app's logic upon receipt of a notification.
- Use cases include tracking user interactions and providing specific content related to the notification.
Example
{
"data": {
"orderNo": "00004196",
"basket": [
{
"sku": "12qw3er56y",
"itemName": "Hand-crafted Peppermint Candy Canes",
qty: 3,
cost: "9.99"
},
{
"sku": "90ujr5383",
"itemName": "Fat Squirrel",
qty: 1,
cost: "29.99"
},
],
"hasDiscountCode": false,
"amount": 65.96
}
}
content_available
content_available
Type bool
Platforms iOS
Description
Controls the background data fetching mechanism on iOS devices. Handy for updating content in the background or performing tasks without user intervention.
true
instructs the system to wake the app from the background and execute custom native code.- Apple interprets this as
content-available=1
.
- Apple interprets this as
- Omit the
contents
parameter to prevent the notification from being presented to the user. - Content-available notifications may not be received by the device if the app has been manually swiped away (Force closed) or if the device is in a power-saving mode.
Example
{
"content_available": true
}
ios_category
ios_category
Type string
Platforms iOS
Description
The Category of the payload for iOS notifications. Enable users to respond directly to a notification without launching the app.
For iOS 10 and later, specifying an ios_category
will activate the corresponding Notification Content Extension in your app that contains the matching category identifier.
Example
Using the "calendar"
category, actions like accept
and decline
can be included to offer users a straightforward way to respond to event invitations directly from the notification.
huawei_msg_type
huawei_msg_type
Type string
Platforms Huawei
Description
Specifies the type of notification being sent to Huawei devices. Each notification type is processed and displayed differently on Huawei devices.
"data"
– Used for notifications containing data payloads you intend to process in the background. These notifications may not be visible to the user but can trigger app actions or data updates."message"
– For notifications intended to be displayed directly to the user.
For details on using these types and their implications on notification delivery and handling, refer to the Data & Background Notifications documentation.
Example
{
"huawei_msg_type": "data"
}
apns_push_type_override
apns_push_type_override
Type string
Platforms iOS
Description
Allows some control over the push type of notification to be sent to APNS. Corresponds to the apns-push-type
header APNS requires which is set to "alert"
or "background"
by us.
Pass "voip"
for notification to initiate VoIP calls or alert the user to incoming VoIP calls.
Example
{
"apns_push_type_override": "voip"
}
huawei_category
huawei_category
Type string
Platforms Huawei
Description
The self-classification category for notifications sent to users in China. Refer to the Huawei Setup Guide for comprehensive setup instructions.
- The category chosen must align with an approved self-classification application.
- By default, the category is set to
MARKETING
- Subject to daily send limitations ranging from 2 to 5, depending on the specific third-level classifications the message falls under.
Available categories include:
IM
VOIP
SUBSCRIPTION
TRAVEL
HEALTH
WORK
ACCOUNT
EXPRESS
FINANCE
DEVICE_REMINDER
MAIL
MARKETING
Example
{
"huawei_category": "IM"
}
huawei_bi_tag
huawei_bi_tag
Type string
Platforms Huawei
Description
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.
Example
{
"huawei_bi_tag": "VIP_OFFER"
}
mutable_content
mutable_content
Type bool
Platforms iOS
Description
Enables your application to modify the content of the notification within the app before it is displayed to the user and track notification receptions. Empowers you to create a more personalized and interactive notification experience by allowing for content modification based on your app's logic or user-specific data. Automatically set to true
and is not configurable. Dynamic and contextual notification content is controlled by thedidReceive(_:withContentHandler:)
method on your Notification Service Extension.
Since it defaults to true
, notifications can always be processed and altered by your app upon receipt, offering a flexible way to manage notification content dynamically.
Example
{
"mutable_content": true
}
Frequency capping & throttling
Control how many push notifications can be sent in a given time. See Push Frequency Capping and Push Throttling for details.
Frequency capping & throttling properties (click to expand)
enable_frequency_cap
enable_frequency_cap
Type bool
Platforms All
Description
Controls the application of Frequency Capping, a feature designed to limit the number of notifications a user receives within a set period to prevent over-notification.
Defaults to the Frequency Capping setting specified in your Dashboard.
true
– ensure the notification adheres to frequency caps when sent.false
– send the notification without regard to frequency capping. Use this option sparingly, reserved for notifications of utmost importance that must reach the user regardless of the frequency cap.
Example
{
"enable_frequency_cap": true
}
throttle_rate_per_minute
throttle_rate_per_minute
Type number
Platforms All
Description
Limit the rate at which notifications are sent out per minute for apps with throttling enabled, providing a mechanism to control the flow of notification delivery.
- Not compatible for use with the
delayed_option
parameter. - This parameter does not affect apps without throttling.
- A non-zero value overrides the default throttling settings from the dashboard.
- Passing a value of
0
disables throttling for the message, allowing it to be sent out without any rate limitation.
Example
Limit message delivery rate to 100 messages per minute.
{
"throttle_rate_per_minute": 100
}
Platform
By default, OneSignal will send to every platform (each platform equals true
).
To only send to specific platforms, you may pass in true
on one or more of these boolean parameters corresponding to the platform you wish to target. If you do so, all other platforms will be set to false
and will not be delivered to.
Enable/Disable Platforms(click to expand)
isIos
isIos
Type bool
Platforms iOS
Description
Specify whether the notification should send to this platform. Omitting this defaults to true
. If you set to true
then all other platforms will be set to false
unless you set them.
Example
{
"isIos": true
}
isAndroid
isAndroid
Type bool
Platforms Android
Description
Specify whether the notification should send to this platform. Omitting this defaults to true
. If you set to true
then all other platforms will be set to false
unless you set them.
Example
{
"isAndroid": true
}
isHuawei
isHuawei
Type bool
Platforms Huawei
Description
Specify whether the notification should send to this platform. Omitting this defaults to true
. If you set to true
then all other platforms will be set to false
unless you set them.
Example
{
"isHuawei": true
}
isAnyWeb
isAnyWeb
Type bool
Platforms Web push
Description
Specify whether the notification should send to this platform. Omitting this defaults to true
. If you set to true
then all other platforms will be set to false
unless you set them.
If you want to target individual browsers, use isChromeWeb
, isFirefox
, or isSafari
.
Example
{
"isAnyWeb": true
}
isChromeWeb
isChromeWeb
Type bool
Platforms Chrome web push
Description
Specify whether the notification should send to this platform. Omitting this defaults to true
. If you set to true
then all other platforms will be set to false
unless you set them.
If you want to target all browsers, use isAnyWeb
.
Example
{
"isChromeWeb": true
}
isFirefox
isFirefox
Type bool
Platforms Firefox
Description
Specify whether the notification should send to this platform. Omitting this defaults to true
. If you set to true
then all other platforms will be set to false
unless you set them.
If you want to target all browsers, use isAnyWeb
.
Example
{
"isFirefox": true
}
isSafari
isSafari
Type bool
Platforms Safari
Description
Specify whether the notification should send to this platform. Omitting this defaults to true
. If you set to true
then all other platforms will be set to false
unless you set them.
If you want to target all browsers, use isAnyWeb
.
Example
{
"isSafari": true
}
isWP_WNS
isWP_WNS
Type bool
Platforms Windows app
Description
Specify whether the notification should send to this platform. Omitting this defaults to true
. If you set to true
then all other platforms will be set to false
unless you set them.
Example
{
"isWP_WNS": true
}
isAdm
isAdm
Type bool
Platforms Amazon
Description
Specify whether the notification should send to this platform. Omitting this defaults to true
. If you set to true
then all other platforms will be set to false
unless you set them.
Example
{
"isAdm": true
}
isChrome
isChrome
Type bool
Platforms Chrome app
Description
Specify whether the notification should send to this platform. Omitting this defaults to true
. If you set to true
then all other platforms will be set to false
unless you set them.
Not for web push. If you want to target all browsers, use isAnyWeb
or isChromeWeb
.
Example
{
"isChrome": true
}