Reference of the Notification object used to specify content when sending notifications via the REST API

This object represents what the user will see. It is split into 3 main fields: alert and push. alert controls what the user will see in the notification center, and push controls various payload and push options.

The simplest form of notification you can create contains only a text alert:

{"alert":{"text": "Hello, WonderPush!"}}

Alert

FieldTypeDescription
alert.textstringThe message to display in the notification center.
alert.titlestringThe title of the notification to display in the notification center.
alert.targetUrla URLThe content that should be displayed when the user clicks the notification.

missing, null or wonderpush://notificationOpen/default, the default.
Simply shows the application.
any deeplink URL (eg.: yourapp://targetScreen?someParams)
The OS of the user device will resolve this accordingly.
any HTTP URL (eg.: https://www.yourwebsite.com/somePage?someTrackingInfo)
The OS of the user device will resolve this accordingly.
It will point to your application if supported, or else will open the web browser.
wonderpush://notificationOpen/broadcast
Lets application code decide what screen to launch.
* wonderpush://notificationOpen/noop
Performs no action. Use this for your notification buttons. Clicking the notification itself should always have some visible feedback so avoid this value.

More info on how to handle your own deeplinks: Android, iOS.
alert.tagstring, null or missingIf a notification using the same tag is currently displayed, it will be updated, otherwise, a new notification is shown.
alert.actionsarray of objectsAn optional list of background actions to perform when the user clicks the notification.

See the list of available actions.
alert.iosobjectiOS specific options
alert.androidobjectAndroid specific options
alert.webobjectWeb specific options

The following table presents the iOS specific options that can be user in the alert.ios field:

FieldTypeDescription
alert.ios.soundstringThe name of a sound file in the app bundle or in the Library/Sounds folder of the app’s data container. The sound in this file is played as an alert. If the sound file doesn’t exist or default is specified as the value, the default alert sound is played. The audio must be in one of the audio data formats that are compatible with system sounds; see UNNotificationSound / Prepare Sounds Resources for details.
alert.ios.badgeintegerThe number to display as the badge of the app icon.
If this property is absent, the badge is not changed. To remove the badge, set the value of this property to 0.
alert.ios.titleLocKeystringThe key to a title string in the Localizable.strings file for the current localization. The key string can be formatted with %@ and %n$@ specifiers to take the variables specified in the alert.ios.titleLocArgs array.
See Localized Formatted Strings for more information.
alert.ios.titleLocArgsarray of stringVariable string values to appear in place of the format specifiers in alert.ios.titleLocKey.
See Localized Formatted Strings for more information.
alert.ios.subtitlestringA second line of title.
alert.ios.subtitleLocKeyThe key to a subtitle string in the Localizable.strings file for the current localization. The key string can be formatted with %@ and %n$@ specifiers to take the variables specified in the alert.ios.subtitleLocArgs array.
See Localized Formatted Strings for more information.
alert.ios.subtitleLocArgsVariable string values to appear in place of the format specifiers in alert.ios.subtitleLocKey.
See Localized Formatted Strings for more information.
alert.ios.bodystringThe text of the alert message.
This field is just like alert.text, but presented with the iOS specific name for convenience.
alert.ios.locKeystringA key to an alert-message string in a Localizable.strings file for the current localization (which is set by the user’s language preference). The key string can be formatted with %@ and %n$@ specifiers to take the variables specified in the alert.ios.locArgs array. See Localized Formatted Strings for more information.
alert.ios.locArgsarray of stringVariable string values to appear in place of the format specifiers in alert.ios.locKey. See Localized Formatted Strings for more information.
alert.ios.actionLocKeystringIf a string is specified, the system displays an alert that includes the Close and View buttons. The string is used as a key to get a localized string in the current localization to use for the right button’s title instead of “View”. See Localized Formatted Strings for more information.
alert.ios.launchImagestringThe filename of an image file in the app bundle, with or without the filename extension. The image is used as the launch image when users tap the action button or move the action slider. If this property is not specified, the system either uses the previous snapshot,uses the image identified by the UILaunchImageFile key in the app’s Info.plist file, or falls back to Default.png.
This property was added in iOS 4.0.
alert.ios.categorystringProvide this key with a string value that represents the identifier property of the UIMutableUserNotificationCategory object you created to define custom actions. To learn more about using custom actions, see Registering Your Actionable Notification Types.
alert.ios.attachmentsarray of objectsA list of media attachments to add to the notification. iOS 10 only shows the first one but you may use the others in you have your own Notification Content Extension. Requires at least SDK v1.2.2.0.
alert.ios.attachments[].idstringAn optional identifier for use in your own Notification Content Extension if you have one.
alert.ios.attachments[].urlstringThe URL to the media to download and attach to the notification.
See the following documentation for supported file formats and associated file size limits.
Prefer using HTTPS.
alert.ios.attachments[].typestringThe type of the file that .url points to. Necessary if the URL does not end with a proper file extension.
Valid official iOS values are: public.png, public.jpeg, com.compuserve.gif, com.microsoft.waveform-audio, public.aiff-audio, public.mp3, public.mpeg-4-audio, public.mpeg, public.mpeg-2-video, public.mpeg-4, public.avi.
Valid file-extension-like values are: png, jpg, jpeg, gif, wav, wave, aiff, mp3, m4a, mp4a, mpg, mpeg, mp2, m2v, mp4, avi.
Valid mime-type-like values are: image/png, image/x-png, image/jpeg, image/gif, audio/wav, audio/x-wav, audio/aiff, audio/x-aiff, audio/mpeg, audio/mp3, audio/mpeg3, audio/mp4, video/mpeg, video/x-mpeg1, video/mpeg2, video/x-mpeg2, video/mp4, video/mpeg4, video/avi.
alert.ios.attachments[].optionsobjectOptional list of additional raw options to pass to the notification attachment constructor method.
alert.ios.contentAvailableintegerProvide this key with a value of 1 to indicate that new content is available. Including this key and value means that when your app is launched in the background or resumed, application:didReceiveRemoteNotification:fetchCompletionHandler: is called.
Note that WonderPush automatically detects when this should be set to 1, like when adding a payload to the notification.
alert.ios.mutableContentintegerProvide this key with a value of 1 to indicate that the Notification Service Extension can run and modify the notification. Necessary for media attachments.
Note that WonderPush sets this to 1 by default in order to support media attachments, but you can override this if necessary.
alert.ios.threadIdstringProvide this key with a string value that represents the app-specific identifier for grouping notifications. If you provide a Notification Content app extension, you can use this value to group your notifications together.
alert.ios.targetContentIdstringThe identifier of the window to bring forward.
alert.ios.foregroundobjectPermits to customize some behavior if the notification is to be displayed while the application is foreground.
alert.ios.foreground.autoOpenbooleanWhether to automatically do as if the user clicked the notification if received while in foreground.
alert.ios.foreground.autoDropbooleanWhether to automatically do as if the user swiped the notification if received while in foreground.
alert.ios.buttonsarray of objectsA list of up to 3 buttons to add to the notification.
alert.ios.buttons[].labelstringThe button label
alert.ios.buttons[].targetUrlURLThe content to open when clicking on the button, as an alternative to clicking on the notification itself.
alert.ios.buttons[].actionsarray of objectsA list of background options to perform when clicking on the button.

See the list of available actions.

You can read more about those fields in the Apple documentation about The Remote Notification Payload.

If neither alert.ios.foreground.autoOpen nor alert.ios.foreground.autoDrop are set, the SDK presents the notification. On iOS 10, if you properly integrated the SDK v1.2.2.0 or later the OS itself will present the notification. On prior versions of iOS or if the your code does not call [WonderPush setupDelegateForUserNotificationCenter] on initialization, the SDK will present an alert with the notification title and text.


The following table presents the Android specific options that can be user in the alert.android field:

FieldTypeDescription
alert.android.channelstringThe Android O notification channel to post the notification to. Prior to Android O, the WonderPush SDK can associate user preferences just about the same way.
The notification uses the default channel configured in the SDK if no value is provided.
alert.android.typestringOne of:

missing, or null: Default style, with expandable text.
none: No style, the text will be shown on a single line.
bigText: In the big text style, the expanded and collapsed state can show a different content.
bigPicture: The big picture style can display a large picture below a line of text.
* inbox: Displays multiple sentences when expanded, each on a single line.
alert.android.bigTitlestring or HTML
Valid for: bigText, bigPicture and inbox.
An alternate title when the notification is expanded.
alert.android.bigTextstring or HTML
Valid for: bigText.
An alternate content when the notification is expanded.
alert.android.summaryTextstring or HTML
Valid for: bigText, bigPicture and inbox.
A last line of text to show under a horizontal ruler.
alert.android.bigLargeIconURL or resource name
Valid for: bigPicture.
An alternate large icon to show then the notification is expanded.
Prefer using HTTPS.
alert.android.bigPictureURL
Valid for: bigPicture.
A large picture to display when the notification is expanded.
Prefer using HTTPS.
alert.android.linesarray of strings or HTML
Valid for: inbox.
A list of single line sentences to show when the notification is expanded.
alert.android.htmlbooleanWhether to treat every displayable string in this object as being HTML styled.
Only simple HTML styling tags are supported by Android
alert.android.titlestring or HTMLSet the first line of text in the platform notification template.
alert.android.textstring or HTMLSet the second line of text in the platform notification template.
alert.android.subTextstring or HTMLThis provides some additional information that is displayed in the notification.
alert.android.infostring or HTMLA small piece of additional information pertaining to this notification.

The platform template will draw this on the last line of the notification, at the far right (to the right of a smallIcon if it has been placed there).
alert.android.tickerstring or HTMLSet the "ticker" text which is sent to accessibility services.
alert.android.prioritystringOne of:

max
high
default
low
* min
alert.android.personsarray of URIsAdd a person that is relevant to this notification. The system will also attempt to resolve mailto: and tel: schema URIs.
alert.android.categorystringOne of the Notification category constants, like message, promo or reminder.
alert.android.colorstringOne of the Color constants, or an #RRGGBB color code.
alert.android.groupstringSet this notification to be part of a group of notifications sharing the same key.

Grouped notifications may display in a cluster or stack on devices which support such rendering.
alert.android.groupTargetUrlstring or nullBy default, clicking on the unfolded group notification will use the targetUrl of the last received notification.

You can override this using this field. You can also give null to prevent the unfolded group notification from being clickable.
alert.android.sortKeystringSet a sort key that orders this notification among other notifications from the same package.

This can be useful if an external sort was already applied and an app would like to preserve this.

Notifications will be sorted lexicographically using this value, although providing different priorities in addition to providing sort key may cause this value to be ignored.
alert.android.localOnlybooleanSet whether or not this notification should not bridge to other devices.

Some notifications can be bridged to other devices for remote display. This hint can be set to recommend this notification not be bridged.
alert.android.numberintegerSet the large number at the right-hand side of the notification.

This is equivalent to alert.android.info, although it might show the number in a different font size for readability.
alert.android.onlyAlertOncebooleanSet this flag if you would only like the sound, vibrate and ticker to be played if the notification is not already showing.
alert.android.whentimestamp in millisecondsAdd a timestamp pertaining to the notification (usually the time the event occurred).

For apps targeting N and above, this time is not shown anymore by default and must be opted into by using alert.android.showWhen.
alert.android.showWhenbooleanControl whether the timestamp set with alert.android.when is shown in the content view.

For apps targeting N and above, this defaults to false.

For earlier apps, the default is true.
alert.android.usesChronometerbooleanShow the when field as a stopwatch. Instead of presenting when as a timestamp, the notification will show an automatically updating display of the minutes and seconds since alert.android.when.

Useful when showing an elapsed time (like an ongoing phone call). The counter can also be set to count down to alert.android.when when using alert.android.chronometerCountDown.
alert.android.chronometerCountDownbooleanSets the Chronometer to count down from alert.android.when, instead of counting up.

This is only relevant if alert.android.usesChronometer has been set to true.
alert.android.timeoutAfterduration in millisecondsSpecifies a duration in milliseconds after which this notification should be automatically closed. This is a built-in Android feature.
alert.android.visibilitystringOne of:

private (the default)
secret
* public
alert.android.lightsboolean or objectSet the desired color for the indicator LED on the device, as well as the blink duty cycle (specified in milliseconds).

Not all devices will honor all (or even any) of these values.

Use false to deactivate, true to user the default values, an object to override some values.
alert.android.lights.colorstringThe LED color.
alert.android.lights.onnumber of millisecondsHow long should the LED stay on.
alert.android.lights.offnumber of millisecondsHow long should the LED stay off.
alert.android.vibrateboolean or array of integersShould the notification vibrate using the default pattern, or the provided one.
alert.android.soundURL or resource identifierSet the sound to play. It will be played using the default audio attributes for notifications.

A notification that is noisy is more likely to be presented as a heads-up notification.
alert.android.ongoingbooleanSet whether this is an "ongoing" notification.

Ongoing notifications cannot be dismissed by the user.
alert.android.progressboolean or 0 to 100 integerSet the progress this notification represents. The platform template will represent this using a progress bar.

Use true to set an undetermined state, or a number from 0 to 100 to set the corresponding percent completion to display.
alert.android.smallIconresource identifierSet the small icon resource, which will be used to represent the notification in the status bar.

The platform template for the expanded view will draw this icon in the left, unless a large icon has also been specified, in which case the small icon will be moved to the right-hand side.
alert.android.largeIconURL or resource identifierAdd a large icon to the notification content view. In the platform template, this image will be shown on the left of the notification view in place of the small icon (which will be placed in a small badge atop the large icon).
Prefer using HTTPS.
alert.android.buttonsarray of objectsA list of up to 3 buttons to add to the notification in the notification center.
alert.android.buttons[].labelstringThe button label.
alert.android.buttons[].iconresource identifierThe icon to display next to the button label.
alert.android.buttons[].targetUrlURLThe content to open when clicking on the button, as an alternative to clicking on the notification itself.
alert.android.buttons[].actionsarray of objectsA list of background options to perform when clicking on the button.

See the list of available actions.
alert.android.allowSystemGeneratedContextualActionsbooleanDetermines whether the platform can generate contextual actions for a notification. Android defaults this to true.
alert.android.badgeIconTypestringSets which icon to display as a badge for this notification. This value might be ignored, for launchers that don't support badge icons.

One of:

none, the default
small
* large
alert.android.colorizedbooleanSet whether this notification should be colorized using alert.android.color for the background color.

This should only be used for high priority ongoing tasks like navigation, an ongoing call, or other similarly high-priority events for the user.

For most alert.android.type styles, the coloring will only be applied if the notification is for a foreground service notification.
alert.android.extrasobjectAny extras to put on the system notification object. Android already puts some keys of its own. These extras can be retreived when listing active notifications in the system.
alert.android.foregroundobjectPermits to override any of the above options if the notification is displayed while the application is foreground.
alert.android.foreground.prioritystringSee alert.android.priority.
Defaults to high in order to get the notification presented as heads-up by the system above your application.
alert.android.foreground.autoOpenbooleanWhether to automatically do as if the user clicked the notification if received while in foreground.
alert.android.foreground.autoDropbooleanWhether to automatically do as if the user swiped the notification if received while in foreground.

HTML styling support is limited to about the following tags:

  • <br>
  • <h1> <h2> <h3> <h4> <h5> <h6>
  • <b> <i> <u> <big> <small> <strong> <em> <strike> <sub> <sup>
  • <a href="http://www.example.com">Link</a>
  • <div align="left|center|right">
  • <p dir="ltr|rtl">
  • <font size="24" color="red" face="Monospace"> <tt>
  • <blockquote> <cite> <dfn>

The following table presents the Web specific options that can be user in the alert.web field:

FieldTypeDescription
alert.web.dirstringauto, ltr or rtl. How the text should be aligned. Helps supporting right-to-left languages.
alert.web.langstringThe notification’s language specifies the primary language for the notification’s title, body and the title of each of its buttons. Its value is a string. The empty string indicates that the primary language is unknown. Any other string must be interpreted as a language tag. Validity or well-formedness are not enforced.
alert.web.bodystringText text to display in the notification. This is the Web specific name of the alert.text field.
alert.web.iconURLThe HTTPS URL of the icon to display next to the notification.
Must use HTTPS.
alert.web.badgeURLA small icon displayed when there is not enough space to display the notification itself. It may also be displayed inside the notification with less visual priority than the icon itself.
Must use HTTPS.
alert.web.imageURLThe HTTPS URL of the big image to display below to the notification.
Must use HTTPS.
alert.web.soundURLThe sound to play.
alert.web.vibratearray of integerThe vibration pattern.
alert.web.timestamptimestamp in millisecondsIndicates the time of the event for which the notification is shown.
alert.web.renotifybooleanIndicates if the user should get a visual notification after a notification has been updated.
alert.web.silentbooleanIndicates that no sounds or vibrations should be made.
alert.web.noscreenbooleanIndicates that the screen of the device should not be enabled.
alert.web.requireInteractionbooleanIndicates that on devices with a sufficiently large screen, the notification should remain readily available until the user activates or dismisses the notification.
WonderPush sets this by default in order to prevent some browsers from automatically dismissing the notification after a few seconds.
alert.web.stickybooleanIndicates that the end user should not be able to easily clear the notification.
alert.web.buttonsarray of objectsA list of buttons to add to the notification.
Note: The Notification API specification uses the name actions for that.
alert.web.buttons[].labelstringThe notification button label.
alert.web.buttons[].actionstringThe notification button identifier. An identifier is automatically generated if not specified.
alert.web.buttons[].iconURLA small button icon to display next to the button label.
alert.web.buttons[].targetUrlURLThe URL of the page to show when clicking on that button, as an alternative to clicking on the notification itself.
alert.web.buttons[].actionsarray of objectsThe optional list of actions that the button should perform.

See the list of available actions.

For more information, you can read the Notification API living standard, but beware, it's a bit dry.

Push options

FieldTypeDescription
push.payloadobjectCustom payload to merge with the notification payload itself.
On the contrary to the custom argument, this enabled you to control the whole notification payload.
Be careful when writing into the _wp field (reserved for the WonderPush SDK) or aps field (reserved for Apple notifications).
push.customobjectA key value mapping of custom data to give in the notification payload under the custom key.
push.expirationDatetimestamp in milliseconds, or a string date using format YYYY-MM-DDTHH:MM:SS.MMM+HH:MMThe date after which the notification should be dropped if not already delivered to a user's device.
Use 0 to try only once.
push.expirationTimeduration in milliseconds, or something like "10 minutes"The duration after which the notification should be dropped if not already delivered to a user's device.
Use 0 to try only once.
push.prioritystringnormal or high
push.receiveActionsarray of objectsAn optional list of background actions to perform when the SDK receives the notification.

See the list of available actions.
push.androidobjectYou can override any of the above keys for Android devices.
The following subkeys allow you to further control some Android-specific options.
push.android.delayWhenIdlebooleanIndicates whether the message should not be sent until the device becomes active.
push.android.collapseKeystringThis parameter defines a group of messages that can be collapsed, so that only the last message gets sent when notifications can be delivered to a device anew.
push.android.restrictedPackageNamestringThis parameter specifies the package name of the application where the registration tokens must match in order to receive the message.
push.iosobjectYou can override any of the above keys for iOS devices.
The following subkeys allow you to further control some Android-specific options.
push.ios.collapseIdstringMultiple notifications with the same collapse identifier are displayed to the user as a single notification on iOS 10+. The value of this key must not exceed 64 bytes.
Defaults to the value of alert.ios.tag or alert.tag, or to the used campaignId.
push.webobjectYou can override any of the above keys for Web devices.
push.web.topicstringCollapsing multiple push messages with the same topic server-side, that is before they are delivered.
32 characters maximum, alphanumeric, dash or underscore ([a-zA-Z0-9_-]).

Available actions for notification clicks and buttons

Each action is composed of a type field, and any additional fields required by the chosen type.
We present below one table per supported action type.

FieldValid forTypeDescription
.typeAllstring"close": Simply closes the in-app dialog box.
If not given explicitly, this action is always added implicitly.

"trackEvent": Tracks a user event.
This has the same effect as if you had called the trackEvent() method of the SDK manually, only you control it dynamically using push notifications.

"updateInstallation": Modify the installation custom properties.
This has the same effect as if you had called the putInstallationCustomProperties() method of the SDK manually, only you control it dynamically using push notifications.

"addProperty": Add one or more values to the existing values of a given property, instead of replacing the whole list.
This has the same effect as if you had called the addProperty() method of the SDK manually, only you control it dynamically using push notifications.

"removeProperty": Add one or more values to the existing values of a given property, instead of replacing the whole list.
This has the same effect as if you had called the removeProperty() method of the SDK manually, only you control it dynamically using push notifications.

"addTag": Add one or more tag.
This has the same effect as if you had called the addTag() method of the SDK manually, only you control it dynamically using push notifications.

"removeTag": Remove one or more tag.
This has the same effect as if you had called the removeTag() method of the SDK manually, only you control it dynamically using push notifications.

"removeAllTags": Remove all tags.
This has the same effect as if you had called the removeAllTags() method of the SDK manually, only you control it dynamically using push notifications.

"method": Automatically triggers a registered callback.
Take a look at the demo applications source code on GitHub to see how you can listen to those callbacks.

"link": Opens the given URL in the browser, or using any application that is bond with it in the system.

"rating": Opens the application store of device platform, on the page corresponding to your application.

"closeNotifications": Selectively closes visible notifications.

"subscribeToNotifications": Subscribes the user to push notifications, possibly prompting her for permission.

"unsubscribeFromNotifications": Unsubscribes the user from push notifications.
.eventtrackEventobjectThe event that should be tracked.
.event.typetrackEventstringThe event type, like the first argument of the trackEvent() method of the SDK.
.event.customtrackEventobjectOptional custom data to attach to the event payload.
See the accepted format.
.installationupdateInstallation
addProperty
removeProperty
objectNew data to merge to the installation. Only the custom field is currently allowed.
Any new field will be created, and any existing field will be overwritten.
See the accepted format of this field.
.custom (deprecated)updateInstallation
addProperty
removeProperty
objectUse "installation": {"custom":…} instead.
.tagsaddTag
removeTag
array of stringsThe list of tags to add or remove.
.methodmethodstringThe callback method name.
.methodArgsmethodstringThe callback argument value.
.urllinkstringThe URL or deeplink to open.
.tagcloseNotificationsstring or nullSelects notifications with the given tag (or without tag if null is given) to be closed.

Note that Android also supports these platform-specific fields:

.channel (string or null): Matches the notification channel. null matches the default channel. See alert.android.channel.
.group (string or null): Matches the notification group key. null matches ungrouped notifications. See alert.android.group.
.category (string or null): Matches the notification category. See alert.android.category.
.sortKey (string or null): Matches the notification sort key. See alert.android.sortKey.

Note that iOS also supports these platform-specific fields:

.threadId (string or null): Matches the notification thread id. See alert.ios.threadId.
.category (string or null): Matches the notification category. See alert.ios.category.
.targetContentId (string or null): Matches the notification target content id. See alert.ios.targetContentId.