Send a message using the push notification channel.

Overview

The Create Notification 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.

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 for sending push notifications, Email Setup for sending emails, and SMS Setup for sending SMS.

Craft your message

Draft the message and embed it in the contents parameter.
English (en) 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.



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

Type object

Platforms All

Description

The message to display in the main body of the notification. This field supports Message Personalization.

Required when

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

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

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 and headings parameters to ensure a unified experience across the notification's title and body.

Example

{
  "subtitle": {
    "en": "English Subtitle",
    "es": "Spanish Subtitle"
  }
}

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

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:
    1. Custom media ID (key)
    2. 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

{
  "ios_attachments": {
    "bg": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
  }
}

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

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

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

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

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

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

Type string

Platforms Huawei

Description

Functionally equivalent to small_icon.

Example

{
  "huawei_small_icon": "your_notification_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

Type string

Platforms Huawei

Description

Functionally equivalent to large_icon.

Example

{
  "huawei_large_icon": "your_large_icon"
}

adm_small_icon

Type string

Platforms Amazon

Description

Functionally equivalent to small_icon.

Example

{
  "adm_small_icon": "your_notification_icon"
}

adm_large_icon

Type string

Platforms Huawei

Description

Functionally equivalent to large_icon.

Example

{
  "adm_large_icon": "your_large_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

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

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

Type string

Platforms Firefox web push

Description

Functionally equivalent to chrome_web_icon.

Example

{
  "firefox_icon": "your_notification_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

Type string

Platforms Android

Description

When targeting Android Oreo (8.0+) or later devices, deliver notifications through a notification channel.

Example

{
  "android_channel_id": "your-channel-uuid"
}

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

Type string

Platforms Huawei

Description

Functionally equivalent to android_channel_id.

Example

{
  "huawei_channel_id": "your-channel-uuid"
}

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

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

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

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

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

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 in ios_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

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

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

Type string

Platforms Huawei

Description

Functionally equivalent to android_accent_color.

Example

{
  "huawei_accent_color": "FFFF0000"
}

apns_alert

Type object

Platforms iOS 10+

Description

It enables you to localize push notifications. 

  • The APNS Alert object should include the loc-key and loc-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

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: 

  1. An offer code to load and a mechanism to track the performance of the offer - message.custom_data.offer_code 

  2. The External ID of the user that can be used for further processing (e.g., updating Data Tags, engagement tracking, etc.) - subscription.external_id

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

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, use url .
  • 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: 

  1. Deep-linking into the StoreApp to open the offer page
  2. The offer code to load - message.custom_data.offer_code

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, use url .

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

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 and text 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

Type [object]

Platforms Chrome web push

Description

Add Action Buttons to web push notifications.

  • Each action button object must include theid and text properties.
  • Include these additional properties to customize appearance and behavior:
    1. icon- URL of an image to display on the button
    2. url - 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

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

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"
}

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

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

Type string

Platforms Amazon

Description

Group notifications on Amazon devices. Similar behavior to android_group parameter.

adm_group_message

Type object

Platforms Amazon

Description

Configure a summary message for notifications grouped together. Similar behavior to android_group parameter.

Example

{
  "adm_group_message": {
    "en": "You have $[notif_count] new messages."
  }
}

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

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

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

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

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

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

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

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

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.

Available categories include:

  • IM
  • VOIP
  • SUBSCRIPTION
  • TRAVEL
  • HEALTH
  • WORK
  • ACCOUNT
  • EXPRESS
  • FINANCE
  • DEVICE_REMINDER
  • MAIL
  • MARKETING

Example

{
  "huawei_category": "IM"
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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
}

Language