contents

Type object

Platforms All

Description

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

Required when:

• content_available is false.
• Or template_id is not 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

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

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": {
    "id": "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.

If you have a Huawei mobile app, Amazon mobile app, and/or Chrome app, use huawei_big_picture, adm_big_picture, and/or chrome_big_picture respectively.

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. macOS does not support this parameter and instead expands the chrome_web_icon. See Web push setup for details.

Example

{
  "chrome_web_image": "https://domain.com/large-image.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.

If you have a Huawei mobile app and/or Amazon mobile app use huawei_small_icon and/or adm_small_icon respectively.

Example

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

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

If you have a Huawei mobile app and/or Amazon mobile app use huawei_large_icon and/or adm_large_icon respectively.

Example

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

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

If you want to change the icons for Firefox and/or your Chrome App, use firefox_icon and/or chrome_icon respectively.

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

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.

If you have your own Android channels setup, you can use the existing_android_channel_id parameter.

If you have a Huawei mobile app use huawei_channel_id.

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.

If you have a Huawei mobile app use existing_huawei_channel_id.

Example

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

priority

Type integer

Platforms iOS, Android, Chrome web push

Description

Determines the delivery priority of notifications through push servers such as Apple Push Notification Service (APNS), Firebase Cloud Messaging (FCM), or Chrome web push. It influences how quickly a notification is delivered to the device, impacting its processing, especially in power-saving modes.

• The value of 10 or higher assigns high priority to the notification; default for iOS.
• Values lower than 10 set the notification to normal priority, ensuring that notifications don't unnecessarily disrupt the user or consume excessive power; default for Android.
• If unset, the fallback will be estimated based on the channel priority, or other content or badge alert parameters set.

Example

{
  "priority": 10
}

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

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

It is recommended to use Android notification categories instead.

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.

If you have a Huawei mobile app, use huawei_accent_color.

Example

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

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.
• See URLs, Links and Deep Links for more details.

Example

{
  "url": "https://store.onesignal.com?offer={{ message.custom_data.offer_code }}&{{ subscription.external_id }}&{{ first_name | 'Friend' }}"`
}

app_url

Type string

Platforms Mobile

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

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

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 integer

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

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.

• 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

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
}

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 integer

Platforms All

Description

Controls the maximum number of notifications sent per minute when throttling is enabled for your app. It is useful for managing traffic spikes, controlling backend load, or ensuring a smoother user experience by gradually delivering notifications.

• Throttling must be enabled in your OneSignal App settings.
• Incompatible with delayed_option parameter. If throttling is enabled, any value passed to delayed_option will be ignored in the request. Set throttle_rate_per_minute to 0 to enable delayed_option settings.
• A value greater than 0 overrides the default throttle rate set in the dashboard.
• A value of 0 disables throttling for that message, allowing full-speed delivery or delayed_option.

Example

Limit message delivery rate to 100 messages per minute.

{
  "throttle_rate_per_minute": 100
}

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
}