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.

contents

Type object

Platforms

Description

The message to display in the main body of the notification.

Required when

• content_available is false
• Or template_id isn't set.

Guidance

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

📘

This field supports Message Personalization.

headings

Type object

Platforms

Description

Specifies the notification's title using a map of language codes to the corresponding title text for each language.

Guidance

• Required for Huawei devices.
• A title is required for Web Push Notifications. Defaults to the "Site Name" specified in Settings in the Dashboard if not provided.
• This parameter is set the same as contents; please see its documentation for more information.

Example

{
  "headings": {
    "en": "English Title",
    "es": "Spanish Title"
  }
}

Language codes must be mirrored in the contents parameter to ensure a unified experience across the notification's title and body.

subtitle

Type object

Platforms

Description

Defines the subtitle of the notification. This parameter enriches the notification's content by providing additional context or information beneath the main title.

Guidance

Behaves the same as contents; please see its documentation for more information.

Example

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

Language codes must be mirrored in the contents and headings parameters to ensure a unified experience across the notification's title and body.

template_id

Type string

Platforms

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.

Guidance

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

content_available

Type bool

Platforms

Description

Controls the background data fetching mechanism on iOS devices. Handy for updating content in the background or performing tasks without user intervention.

Guidance

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

Example

{
  "content_available": true
}

💡

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.

mutable_content

Type bool

Platforms

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.

Guidance

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
}

💡

Dynamic and contextual notification content is controlled by thedidReceive(_:withContentHandler:) method on your Notification Service Extension.

target_content_identifier

Type string

Platforms

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.

Attachments

data

Type object

Platforms

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, enabling you to embed rich, contextual information directly within your notifications.

Guidance

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

url

Type string

Platforms

Description

The URL will be opened in the browser when a user interacts with the notification. Supports Tag Substitution, empowering you to dynamically customize URLs to drive traffic and direct engagement with web content.

Guidance

• 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

Description

It performs a similar function to the url parameter but exclusively targets mobile & desktop push platforms like iOS, Android, ChromeApps, and other app platforms. Setting will cause the URL to open within your app.

Guidance

• 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

🚧

Don't use in conjunction with app_url or web_url to prevent issues with notification behavior.

web_url

Type string

Platforms

Description

It performs a similar function to the url parameter but exclusively targets web push platforms like Chrome, Firefox, Safari, and other browsers. 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.

ios_attachments

Type object

Platforms

Description

Include local and remote content in your notifications to boost engagement with improved 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.

Guidance

• Refer to Images & Rich Mediafor 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

Example

{
  "bg": "https://store.onesignal.com/assets/offers/bg_vip_offer.jpg",
  "offerHero": "https://store.onesignal.com/offers/vip-offer-2/hero.jpg"
}

💡

Setting mutable_content is unnecessary for downloading attachments; the OneSignal iOS SDK does this automatically.

chrome_web_image

Type string

Platforms

Description

It serves the same purpose as big_picture for the Chrome web browser.

Guidance

For guidelines on optimizing the image for web push notifications and ensuring device compatibility, refer to Web Push Notification Icons.

Example

{
  "chrome_web_image": "https://domain.com/large-image.jpg"
}

🚧

Chrome for macOS doesn't support this parameter; use chrome_web_icon instead.

big_picture

Type string

Platforms

Description

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

Guidance

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

adm_big_picture

Type string

Platforms

Description

It 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

Description

It serves the same purpose as big_picture for Chrome Apps.

Example

{
  "chrome_big_picture": "https://store.onesignal.com/offers/vip-offer-2/hero.jpg"`
}

huawei_big_picture

Type string

Platforms

Description

It serves the same purpose as big_picture for Huawei devices.

Example

{
  "huawei_big_picture": "https://store.onesignal.com/offers/vip-offer-2/hero.jpg"`
}

huawei_msg_type

Type string

Platforms

Description

Specifies the type of notification being sent to Huawei devices. Each notification type is processed and displayed differently on Huawei devices.

Guidance

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

huawei_category

Type string

Platforms

Description

The self-classification category for notifications sent to users in China. The category chosen must align with an approved self-classification application.

Guidance

• 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

💡

Refer to the Huawei Setup Guide for comprehensive setup instructions.

Example

{
  "huawei_category": "IM"
}

huawei_bi_tag

Type string

Platforms

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.

Guidance

You can set this parameter to track the performance of your push campaigns and optimization of your messaging strategy.

Example

{
  "huawei_bi_tag": "VIP_OFFER"
}

Action Buttons

Allow users to take more than one action on a notification. Learn more about Action Buttons.

buttons

Type [object]

Platforms

Description

This feature lets you provide clear actions for users to take directly from the notification pane.

Guidance

• 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

Description

Add Action Buttons to web push notifications.

Guidance

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

ios_category

Type string

Platforms

Description

The Category of the payload for iOS notifications. Enable users to respond directly to a notification without launching the app.

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

icon_type

Type string

Platforms

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.

Guidance

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

Appearance

These parameters let you adjust icons, badges, and other appearance changes to your push notifications.

Android & Huawei Notification Categories / Channels

The OneSignal SDK facilitates the customization of notifications for  Android and Huawei devices running Android 8 (Oreo) and newer, including options for Importance, Sound, Vibration, LED Color, Badges, and Lockscreen Visibility. These customization features require android_channel_id; if set, the SDK automatically handles compatibility fallbacks for Android 7 and older devices. Refer to the Category documentation for more detailed guidance on creating and utilizing these options.

Icons - Different platforms handle icons differently.

The handling of notification icons varies across platforms when using the OneSignal SDK. On Android, a bell icon is displayed by default but can be customized, as detailed in the Android Notification Icons guide. For Huawei devices, the default is the app icon, with customization options also available in the same guide. On iOS, however, the notification icon is consistently the app icon, with no customization option.

Badges - Useful to indicate to the user the number of notifications outstanding.

Badges serve as a helpful indicator of the number of outstanding notifications on a user's device. On iOS, the badge number on the app icon has to be customized to reflect a specific count; however, on Android, the badge number automatically updates the total number of notifications in the notification shade.

android_channel_id

Type string

Platforms

Description

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

Guidance

Use the Channel ID from the notification channel configured in the app Dashboard.

Example

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

💡

Refer to Android Notification Categories for more information.

huawei_channel_id

Type string

Platforms

Description

Functionally equivalent to android_channel_id.

Example

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

existing_android_channel_id

Type string

Platforms

Description

Functionally equivalent to android_channel_id, except you may specify a notification channel created outside the Dashboard.

Example

{
	"existing_android_channel_id": "your-predefined-channel-id" 
}

💡

Refer to the Android documentation on creating notification channels and obtaining their IDs to ensure correct implementation and usage within your notification strategy.

huawei_existing_channel_id

Type string

Platforms

Description

Functionally equivalent to existing_android_channel_id.

Example

{
  "huawei_existing_channel_id": "your-predefined-channel-id"
}

small_icon

Type string

Platforms

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.

Guidance

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

Example

Set the custom icon to an app resource named "your_notification_icon".

{
  "small_icon": "your_notification_icon"
}

💡

Refer to the guide on How to create small icons for detailed instructions on designing and implementing custom notification icons in your Android application.

huawei_small_icon

Type string

Platforms

Description

Functionally equivalent to huawei_small_icon.

Example

{
  "huawei_small_icon": "your_notification_icon"
}

large_icon

Type string

Platforms

Description

Specify the large icon within the notification content area, distinct from the smaller status bar icon for the notification.

Guidance

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.
• The notification will display the standard large icon defined in the app's notification template or the Android system default if not set.

Example

Use a custom resource named "your_large_icon" stored in the app's drawable resources.

{
  "large_icon": "your_large_icon"
}

💡

For detailed guidance on designing and implementing custom icons for your notifications, refer to the documentation on creating large icons.

huawei_large_icon

Type string

Platforms

Description

Functionally equivalent to large_icon.

Example

{
  "huawei_large_icon": "your_large_icon"
}

adm_small_icon

Type string

Platforms

Description

Functionally equivalent to small_icon.

Example

{
  "adm_small_icon": "your_notification_icon"
}

adm_large_icon

Type string

Platforms

Description

Functionally equivalent to large_icon.

Example

{
  "adm_large_icon": "your_large_icon"
}

chrome_web_icon

Type string

Platforms

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.

Guidance

• 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

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.

Guidance

Provide a URL to the image to display. The image must be web-accessible and optimized for quick loading.

Example

{
  "chrome_web_image": "https://domain.com/path/to/large-image.png"
}

💡

Refer to the Web Push Notification Icons guidelines to learn size recommendations for web notification images along with other best practices.

chrome_web_badge

Type string

Platforms

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.

Guidance

Provide a URL pointing to the image for the badge icon. Ensure the image is web-accessible and optimized for small sizes for clarity.

Example

{
  "chrome_web_badge": "https://domain.com/path/to/badge-icon.png"
}

💡

Refer to the Web Push Notification Badge documentation for guidelines on creating an effective badge icon, including size recommendations and design tips.

firefox_icon

Type string

Platforms

Description

Functionally equivalent to chrome_web_icon.

Example

{
  "firefox_icon": "your_notification_icon"
}

chrome_icon

Type string

Platforms

Description

Specify the icon, separate from the app icon, for notifications targeting Chrome Apps.

Guidance

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

🚧

Not applicable for web push notifications

To set the notification icon for web push on Chrome, refer to chrome_web_icon.

ios_sound

Type string

Platforms

Description

Specify a custom sound file to play when the notification is received instead of the default sound.

Guidance

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

Example

{
  "ios_sound": "notification.wav"
}

💡

Ensure the sound file (e.g., '.wav') is supported by iOS for notification sounds and is correctly bundled with your app.

wp_wns_sound

Type string

Platforms

Description

Functionally equivalent to ios_sound.

Guidance

The sound file should be properly bundled with your Windows app.

Example

{
  "wp_wns_sound": "notification.wav"
}

android_accent_color

Type string

Platforms

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.

Guidance

Specify the color using ARGB Hex format.

Example

{
  "android_accent_color": "FFFF0000"
}

huawei_accent_color

Type string

Platforms

Description

Functionally equivalent to android_accent_color.

Example

{
  "huawei_accent_color": "FFFF0000"
}

ios_badgeType

Type string

Platforms

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.

Guidance

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

Description

Works with ios_badgeType to determine the numerical change to your app's badge count.

Guidance

The provided value must be a whole number.

Example

{
  "ios_badgeType": "SetTo",
  "ios_badgeCount": 5
}

apns_alert

Type object

Platforms

Description

It enables you to localize push notifications. 

Guidance

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

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

💡

For other APNS Alert parameters, refer to Apple's documentation.

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.

android_group

Type string

Platforms

Description

Group notifications on Android devices. Notifications with the same group identifier are grouped using Android's Notification Grouping feature.

Guidance

• 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

Description

Group notifications on Amazon devices.

Guidance

Similar behavior to android_group parameter.

adm_group_message

Type object

Platforms

Description

Configure a summary message for notifications grouped together.

Guidance

Similar behavior to android_group_message parameter.

Example

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

collapse_id

Type string

Platforms

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.

Guidance

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

Example

{
  "collapse_id": "update_notification_12345"
}

web_push_topic

Type string

Platforms

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.

Guidance

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

thread_id

Type string

Platforms

Description

Organize notifications on Apple devices by grouping related notifications.

Guidance

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

Type string

Platforms

Description

Use in conjunction with thread_id to specify a name or identifier (such as a person or a topic) for a notification group.

Guidance

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

Type number

Platforms

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.

Guidance

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

Type number

Platforms

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.

Guidance

A higher score suggests greater relevance. Notifications with higher scores are displayed first in the group.

Example

{
  "ios_relevance_score": 0.8
}

☝️A good choice for a time-sensitive notification.

ios_interruption_level

Type string

Platforms

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.

Guidance

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

Example

{
  "ios_interruption_level": "critical"
}

💡

Notifications marked critical are always presented to the user even when Do Not Disturb is active and thus requires a special entitlement.

Delivery

ttl

Type number

Platforms

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.

Guidance

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
}

priority

Type number

Platforms

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.

Guidance

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

💡

Android 6 and later

High-priority notifications can wake the device from Doze mode, ensuring the notification is delivered promptly, even in low-power mode.

enable_frequency_cap

Type bool

Platforms

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.

Guidance

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
}

💡

Frequency Capping is available on select plans. Enable it from the Dashboard.

apns_push_type_override

Type string

Platforms

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.

Guidance

Pass "voip" for notification to initiate VoIP calls or alert the user to incoming VoIP calls.

Example

{
  "apns_push_type_override": "voip"
}

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.

isIos

Type bool

Platforms

Description

Specify whether the notification should exclusively target iOS devices.

Guidance

Set to true to send the notification only to iOS devices.

Example

{
  "isIos": true
}

isAndroid

Type bool

Description

Specify whether the notification should exclusively target Android devices.

Guidance

Behavior is the same as isIos, but for Android devices.

Example

{
  "isAndroid": true
}

isHuawei

Type bool

Platforms

Description

Specify whether the notification should exclusively target Huawei devices.

Guidance

Behavior is the same as isIos, but for Huawei devices.

Example

{
  "isHuawei": true
}

isAnyWeb

Type bool

Platforms

Description

Specify whether the notification should exclusively target web browsers.

Guidance

Behavior is the same as isIos, but for web browsers.

Example

{
  "isAnyWeb": true
}

💡

Target individual browsers with isChromeWeb, isFirefox, or isSafari.

isChromeWeb

Type bool

Platforms

Description

Specify whether the notification should exclusively target Chrome web browsers.

Guidance

Behavior is the same as isIos, but for Chrome web browsers.

Example

{
  "isChromeWeb": true
}

isFirefox

Type bool

Platforms

Description

Specify whether the notification should exclusively target Firefox web browsers.

Guidance

Behavior is the same as isIos, but for Firefox web browsers.

Example

{
  "isFirefox": true
}

isSafari

Type bool

Platforms

Description

Specify whether the notification should exclusively target Safari web browsers.

Guidance

Behavior is the same as isIos, but for Safari web browsers.

Example

{
  "isSafari": true
}

isWP_WNS

Type bool

Platforms

Description

Specify whether the notification should exclusively target Windows devices.

Guidance

Behavior is the same as isIos, but for Windows devices.

Example

{
  "isWP_WNS": true
}

isAdm

Type bool

Platforms

Description

Specify whether the notification should exclusively target Amazon devices.

Guidance

Behavior is the same as isIos, but for Amazon devices.

Example

{
  "isAdm": true
}

isChrome

Type bool

Platforms

Description

Specify whether the notification should exclusively target Chrome apps.

Guidance

Behavior is the same as isIos, but for Chrome Apps.

Example

{
  "isChrome": true
}

🚧

Not for Chrome Web Browsers

Use isChromeWeb to target Chrome web browsers