Progress will discontinue Telerik Platform on May 10th, 2018. Learn more

Push Notification Object Fields Reference

Push Notification Object Fields Reference

When composing a push notification you can provide various optional information that allows you to control scheduling, expiration, vendor-specific settings, and so on. When these options are not set, default values are used that aim to provide the best experience on all supported platforms.

Setting Options

To set an option, add it to the JSON notification object.

The supported options are listed in the sections below.

Generic Fields

Property Name Value Type Description
Message String A default message that is sent to each platform for which a vendor-specific payload is not provided. Treated differently on each platforms (e.g. it appears as an alert on iOS). Note that different platforms have different limits on message length.
Filter String A filter expression specifying which devices must receive the push notification. It represents a stringified JSON object.
NotificationDate Date Date and time when you want the push notification to be sent. Uses ISO 8601 format.
ExpirationDate Date Date and time when the push notification expires. The server stops retrying to send the message to failed devices after this date. Uses ISO 8601 format.
UseLocalTime Boolean Specifies whether the NotificationDate should be treated as a local time for the device. If true, the device will receive the message when its local time coincides with the time component of NotificationDate (in this case the NotificationDate is first converted to UTC and then its time zone ignored). Can be used only when the NotificationDate field is specified.
OptionalHeaders Object Any headers you specify here are passed without modification to the Windows Push Notification Service (WNS).

Android-Specific Fields

Property Name Value Type Description
Android object Container for all Android-specific options.
Android.data object A JSON object whose fields represent the key-value pairs of the message's payload data.
Android.data.largeIcon string Specifies a PNG image to be displayed in the expanded notification drawer. Omit the file extension. The file must be located in platforms/android/res/drawable* (App_Resources/Android/drawable* in AppBuilder). Requires the Telerik Push Notifications plug-in.
Android.data.message string A string representing the message that will be sent to Android devices.
Android.data.msgcnt number A number that will be shown next to the message in the notification bar.
Android.data.smallIcon string Specifies a PNG image (max. 24x24dp) to be displayed in the status bar. Omit the file extension. The file must be located in platforms/android/res/drawable* (App_Resources/Android/drawable* in AppBuilder). Requires the Telerik Push Notifications plug-in.
Android.data.sound string Specifies a sound file to be played when a push notification arrives. Omit the file extension. The file must be located in platforms/android/res/raw/ (App_Resources/Android/raw/ in AppBuilder). Supported formats: Android media formats. Requires the Telerik Push Notifications plug-in.
Android.data.title string A string that will be displayed on the device as app title.
Android.data.<custom-key-name> string or object Custom data that you would like to handle client-side.
Android.collapse_key string An arbitrary string (such as "Updates Available") that is used to collapse a group of similar messages sent while the device was offline, so that only the last message gets sent to the client.
Android.delay_while_idle bool Deprecated Indicates that the message will not be sent immediately if the device is idle.
Android.time_to_live number How long (in seconds) the message will be kept on the server before it expires. Equivalent to ExpirationDate.
Android.retries number Indicates how many times the server will try to send the message.
Android.data.color string Specifies a color that will appear in the background circle behind the large notification icon on Android 5+. Requires the Telerik Push Notifications plug-in. Can be a color name ("red") or a hex value ("#ff0000").
Android.priority string (Requires Android 6.0+) Determines if the notification is delivered with priority or device power saving is taken into account. Possible values: high (send immediately), normal (delay and group with other messages; some messages may not be delivered). Default: high. The values high and normal correspond to priority 10 and 5 of APNS.
Android.notification object Specifies the predefined, user-visible key-value pairs of the notification payload. Some of the pairs may require you to handle them manually in the client.

iOS-Specific Fields

Property Name Value Type Description
IOS object Container for all iOS-specific options. Must contain the _aps_ property. Custom properties that are not listed in this table are also allowed.
IOS.aps object Container for the push notification actions.
IOS.aps.alert string or object If this property is included, the system displays a standard alert. If you specify a string, it becomes the message text of an alert.
IOS.aps.alert.body string The main text of the alert message.
IOS.aps.alert.title string A string summarizing the purpose of the alert in a few short words. Apple Watch displays it as part of the notification interface.
IOS.aps.alert.subtitle string (Requires iOS 10+) A short caption that appears below IOS.aps.alert.title on the alert.
IOS.aps.alert.action-loc-key string This string is used as a key to get a localized string to use in place of the View button's label. If the value is null, the system displays an alert with a single OK button.
IOS.aps.alert.loc-key string A key to an alert-message string in a Localizable.strings file for the current locale. The key string can be formatted with %@ and %n$@ specifiers to take the variables specified in loc-args.
IOS.aps.alert.loc-args array Variable string values to appear in place of the format specifiers in loc-key.
IOS.aps.alert.launch-image string An image filename. The specified image is used as the launch image when users tap the action button or move the action slider.
IOS.aps.badge number or string The number to display as the badge of the application icon. If you want to increment/decrement the badge number, you can send a string specifying the change. Specifying 0 will remove the badge. Example values: 1, "+30", "-1", 0
IOS.aps.sound string Specifies a sound file to be played when a push notification arrives. The file must be located in the application root. In hybrid apps, prefix with www/. Set to "default" to use the default sound for the device.
IOS.aps.category string (Requires iOS 8+) The name of the category in the client app that specifies the actions that will be used in an interactive push notification.
IOS.aps.content-available number If your app is configured to handle silent push notifications in background mode, set this key to 1 in the payload to notify the app to execute the background processing task. Additional configuration needed for Hybrid apps, see Handling Push Notifications in a Hybrid or NativeScript App.
IOS.aps.collapseId string (Requires iOS 10+) Set this parameter to create an ID for a notification. Consequent notification that you send with the same ID will update (overwrite) the original if the user hasn't read it yet. If the notification has been read, the update appears as a new notification.
IOS.aps.priority number Determines if the notification is delivered with priority or device power saving is taken into account. Possible values: 10 (send immediately), 5 (delay and group with other messages; some messages may not be delivered). Default: 10.
IOS.aps.threadId string Translates as the iOS thread-id key. This key is not handled automatically by iOS. You need to implement native code to handle it as you see fit.
IOS.<custom-key-name> string or object Custom data you would like to handle client-side.

Windows Phone-Specific Fields

Property Name Value Type Description
WindowsPhone object Container for all Windows Phone-specific options. It always contains a single field—Toast, Tile, or Raw (indicating the push type)—where all other options go.
WindowsPhone.Toast object Settings for the toast notification type. If null, no toast notification will be sent.
WindowsPhone.Toast.Title string The title for the toast notification.
WindowsPhone.Toast.Message string The message for the toast notification.
WindowsPhone.Toast.LandingUri string Relative URI of the page to navigate to when the toast is tapped. If null, the notification opens the main page. Example: /PageName.xaml.
WindowsPhone.Tile object Settings for the tile notification type. If null, no tile notification will be sent.
WindowsPhone.Tile.TileId string The URI of the tile to update. Only used when updating secondary tiles. If null, the primary tile will be updated. Example: /MyLandingPage.xaml.
WindowsPhone.Tile.Title string The title displayed on the front side of the tile. This field is mandatory.
WindowsPhone.Tile.BackgroundImage string A background image to use for the tile's front side. Example: Images/MyImage.png
WindowsPhone.Tile.Count number The count value to show on the tile. Range: 1 to 99.
WindowsPhone.Tile.BackTitle string The title displayed on the back side of the tile.
WindowsPhone.Tile.BackContent string Text to be displayed on the back side of the tile.
WindowsPhone.Tile.BackBackgroundImage string A background image for the tile's back side. Example: Images/MyImage.png
WindowsPhone.Tile.SmallBackgroundImage string An image to use for the small tile. Supported from Windows Phone 7.8. Example: Images/MyImage.png
WindowsPhone.Tile.WideBackgroundImage string An image to use for the front side of the wide tile. Supported on Windows Phone 7.8 and later. Example: Images/MyImage.png
WindowsPhone.Tile.WideBackBackgroundImage string An image to use for the back side of the wide tile. Supported on Windows Phone 7.8 and later. Example: Images/MyImage.png
WindowsPhone.Tile.WideBackContent string Text to be displayed on the wide tile. Supported on Windows Phone 7.8 and later.
WindowsPhone.Raw object Settings for the Raw notification type.
WindowsPhone.Raw.Payload string The payload for the raw notification.

Windows-Specific Fields

Property Name Value Type Description
Windows object Container for all Windows-specific options.
Windows.Toast object Settings for the toast notification type.
Windows.Toast.template string Template on which to base the toast. See "Toast.visual.binding.template" for the full list. Not allowed when Toast.visual is set.
Windows.Toast.text array An array of strings or "text" objects that will be used according to the template structure. Not allowed when "Toast.visual" is set.
text object Specifies text used in the toast template.
text.id number The text element in the toast template that this text is intended for. If a template has only one text element, then this value is 1. The number of available text positions is based on the template definition.
text.text string Specifies text used in the toast template.
text.lang string The target locale of the XML payload specified as a BCP-47 language tags such as "en-US" or "fr-FR". Overrides any other locale specifications in "binding" or "visual". If its value is a literal string, this attribute defaults to the user's UI language. If its value is a string reference, this attribute defaults to the locale chosen by Windows Runtime in resolving the string.
Windows.Toast.image array An array of strings or "image" objects that will be used according to the template structure. Not allowed when "Toast.visual" is set.
image.id number The image element in the toast template that this image is intended for. If a template has only one image, then this value is 1. The number of available image positions depends on the template definition.
image.src string The URI of the image source.
image.alt string A description of the image for users of assistive technologies.
image.addImageQuery boolean Set to "true" to allow Windows to append a query string to the image URI supplied in the toast notification. Use this attribute if your server hosts images and can handle query strings, either by retrieving an image variant based on the query strings or by ignoring the query string and returning the image as specified without the query string. This query string specifies scale, contrast setting, and language; for instance, a value of "www.website.com/images/hello.png" given in the notification becomes "www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us"
Windows.Toast.visual object Contains a single binding element that defines a toast.
Windows.Toast.visual.version number The version of the toast XML schema that this particular payload was developed for.
Windows.Toast.visual.lang string The target locale of the XML payload, specified as BCP-47 language tags such as "en-US" or "fr-FR". This locale is overridden by any locale specifications in "binding" or "text". If its value is a literal string, this attribute defaults to the user's UI language. If its value is a string reference, this attribute defaults to the locale chosen by Windows Runtime in resolving the string.
Windows.Toast.visual.baseUri string A default base URI that is combined with relative URIs in image source attributes.
Windows.Toast.visual.addImageQuery boolean Set to "true" to allow Windows to append a query string to the image URI supplied in the toast notification. Use this attribute if your server hosts images and can handle query strings, either by retrieving an image variant based on the query strings or by ignoring the query string and returning the image as specified without the query string. This query string specifies scale, contrast setting, and language; for instance, a value of "www.website.com/images/hello.png" given in the notification becomes "www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us"
Windows.Toast.visual.binding object Specifies the toast template. Note that only a single binding element can be included in a toast notification.
Windows.Toast.visual.binding.template string (Required) Template on which to base the toast. Possible values:
  • "ToastImageAndText01"
  • "ToastImageAndText02"
  • "ToastImageAndText03"
  • "ToastImageAndText04"
  • "ToastText01"
  • "ToastText02"
  • "ToastText03"
  • "ToastText04"
Windows.Toast.visual.binding.fallback string A template to use if the primary template cannot be found, for backward compatibility.
Windows.Toast.visual.binding.lang string The target locale of the XML payload, specified as a BCP-47 language tags such as "en-US" or "fr-FR". The locale specified here overrides that in "visual", but can be overridden by that in "text". If its value is a literal string, this attribute defaults to the user's UI language. If its value is a string reference, this attribute defaults to the locale chosen by Windows Runtime in resolving the string.
Windows.Toast.visual.binding.addImageQuery boolean Set to "true" to allow Windows to append a query string to the image URI supplied in the toast notification. Use this attribute if your server hosts images and can handle query strings, either by retrieving an image variant based on the query strings or by ignoring the query string and returning the image as specified without the query string. This query string specifies scale, contrast setting, and language; for instance, a value of "www.website.com/images/hello.png" given in the notification becomes "www.website.com/images/hello.png?ms-scale=100&ms-contrast=standard&ms-lang=en-us"
Windows.Toast.visual.binding.baseUri string A default base URI that is combined with relative URIs in image source attributes.
Windows.Toast.visual.binding.text array An array of strings or "text" objects that will be used according to the template structure.
Windows.Toast.visual.binding.image array An array of strings or "image" objects that will be used according to the template structure.
Windows.Toast.launch string A string that is passed to the application when it is activated by the toast. Format and contents are defined by the app for its own use. When the user taps or clicks the toast, the launch string provides context to the app that allows it to show the user a view relevant to the toast content, rather than a default view.
Windows.Toast.duration string The amount of time the toast should display. Possible values: "long", "short"
Windows.Toast.audio object Specifies a sound to play when a toast notification is displayed. This element also allows you to mute any toast notification audio.
Windows.Toast.audio.src string Specifies a notification sound for the toast. Possible values:
  • ms-winsoundevent:Notification.Default
  • ms-winsoundevent:Notification.IM
  • ms-winsoundevent:Notification.Mail
  • ms-winsoundevent:Notification.Reminder
  • ms-winsoundevent:Notification.SMS
  • ms-winsoundevent:Notification.Looping.Alarm
  • ms-winsoundevent:Notification.Looping.Alarm2
  • ms-winsoundevent:Notification.Looping.Alarm3
  • ms-winsoundevent:Notification.Looping.Alarm4
  • ms-winsoundevent:Notification.Looping.Alarm5
  • ms-winsoundevent:Notification.Looping.Alarm6
  • ms-winsoundevent:Notification.Looping.Alarm7
  • ms-winsoundevent:Notification.Looping.Alarm8
  • ms-winsoundevent:Notification.Looping.Alarm9
  • ms-winsoundevent:Notification.Looping.Alarm10
  • ms-winsoundevent:Notification.Looping.Call
  • ms-winsoundevent:Notification.Looping.Call2
  • ms-winsoundevent:Notification.Looping.Call3
  • ms-winsoundevent:Notification.Looping.Call4
  • ms-winsoundevent:Notification.Looping.Call5
  • ms-winsoundevent:Notification.Looping.Call6
  • ms-winsoundevent:Notification.Looping.Call7
  • ms-winsoundevent:Notification.Looping.Call8
  • ms-winsoundevent:Notification.Looping.Call9
  • ms-winsoundevent:Notification.Looping.Call10
Windows.Toast.audio.loop boolean True if the sound should repeat until addressed; false to play only once. If this field is set to true, the "Toast.duration" field in the toast element must also be set.
Windows.Toast.audio.silent boolean True to mute the sound; false to allow the toast notification sound to play.
Windows.Toast.commands object Specifies that the toast notification is being used to indicate an incoming call or an alarm, with appropriate commands associated with each scenario.
Windows.Toast.commands.scenario string The intended use of the notification. Possible values: "alarm", "incomingCall"
Windows.Toast.commands.command array An array of "command" objects.
command object Specifies a scenario-associated button shown in a toast. The scenario is specified in the parent commands element.
command.id string Specifies a single command from the system-defined command list. Each command can only be used with a particular scenario: "alarm": "snooze", "dismiss"; "incomingCall": "video", "voice", "decline"
command.arguments string An string of arguments that can be passed to the associated app to provide specifics about the action that it should execute in response to the user action.
Windows.Tile object Base tile element, which contains a single visual element.
Windows.Tile.template string A template on which to base the tile. Typically, a developer should supply both a square and a wide format, each as a separate binding object. Possible values:
  • "TileSquare150x150Block"
  • "TileSquare150x150Image"
  • "TileSquare150x150PeekImageAndText01"
  • "TileSquare150x150PeekImageAndText02"
  • "TileSquare150x150PeekImageAndText03"
  • "TileSquare150x150PeekImageAndText04"
  • "TileSquare150x150Text01"
  • "TileSquare150x150Text02"
  • "TileSquare150x150Text03"
  • "TileSquare150x150Text04"
  • "TileSquare310x310BlockAndText01"
  • "TileSquare310x310BlockAndText02"
  • "TileSquare310x310Image"
  • "TileSquare310x310ImageAndText01"
  • "TileSquare310x310ImageAndText02"
  • "TileSquare310x310ImageAndTextOverlay01"
  • "TileSquare310x310ImageAndTextOverlay02"
  • "TileSquare310x310ImageAndTextOverlay03"
  • "TileSquare310x310ImageCollection"
  • "TileSquare310x310ImageCollectionAndText01"
  • "TileSquare310x310ImageCollectionAndText02"
  • "TileSquare310x310SmallImagesAndTextList01"
  • "TileSquare310x310SmallImagesAndTextList02"
  • "TileSquare310x310SmallImagesAndTextList03"
  • "TileSquare310x310SmallImagesAndTextList04"
  • "TileSquare310x310Text01"
  • "TileSquare310x310Text02"
  • "TileSquare310x310Text03"
  • "TileSquare310x310Text04"
  • "TileSquare310x310Text05"
  • "TileSquare310x310Text06"
  • "TileSquare310x310Text07"
  • "TileSquare310x310Text08"
  • "TileSquare310x310TextList01"
  • "TileSquare310x310TextList02"
  • "TileSquare310x310TextList03"
  • "TileWide310x150BlockAndText01"
  • "TileWide310x150BlockAndText02"
  • "TileWide310x150Image"
  • "TileWide310x150ImageAndText01"
  • "TileWide310x150ImageAndText02"
  • "TileWide310x150ImageCollection"
  • "TileWide310x150PeekImage01"
  • "TileWide310x150PeekImage02"
  • "TileWide310x150PeekImage03"
  • "TileWide310x150PeekImage04"
  • "TileWide310x150PeekImage05"
  • "TileWide310x150PeekImage06"
  • "TileWide310x150PeekImageAndText01"
  • "TileWide310x150PeekImageAndText02"
  • "TileWide310x150PeekImageCollection01"
  • "TileWide310x150PeekImageCollection02"
  • "TileWide310x150PeekImageCollection03"
  • "TileWide310x150PeekImageCollection04"
  • "TileWide310x150PeekImageCollection05"
  • "TileWide310x150PeekImageCollection06"
  • "TileWide310x150SmallImageAndText01"
  • "TileWide310x150SmallImageAndText02"
  • "TileWide310x150SmallImageAndText03"
  • "TileWide310x150SmallImageAndText04"
  • "TileWide310x150SmallImageAndText05"
  • "TileWide310x150Text01"
  • "TileWide310x150Text02"
  • "TileWide310x150Text03"
  • "TileWide310x150Text04"
  • "TileWide310x150Text05"
  • "TileWide310x150Text06"
  • "TileWide310x150Text07"
  • "TileWide310x150Text08"
  • "TileWide310x150Text09"
  • "TileWide310x150Text10"
  • "TileWide310x150Text11"
Not allowed when "Tile.visual" is set.
Windows.Tile.fallback string A template to use if the primary template name is not recognized by the recipient. Used for compatibility with Windows 8. This value is the Windows 8 name of the value in the template attribute. New templates introduced after Windows 8 do not have a fallback. This field can have one of following values:
  • "TileSquareBlock"
  • "TileSquareImage"
  • "TileSquarePeekImageAndText01"
  • "TileSquarePeekImageAndText02"
  • "TileSquarePeekImageAndText03"
  • "TileSquarePeekImageAndText04"
  • "TileSquareText01"
  • "TileSquareText02"
  • "TileSquareText03"
  • "TileSquareText04"
  • "TileWideBlockAndText01"
  • "TileWideBlockAndText02"
  • "TileWideImage"
  • "TileWideImageAndText01"
  • "TileWideImageAndText02"
  • "TileWideImageCollection"
  • "TileWidePeekImage01"
  • "TileWidePeekImage02"
  • "TileWidePeekImage03"
  • "TileWidePeekImage04"
  • "TileWidePeekImage05"
  • "TileWidePeekImage06"
  • "TileWidePeekImageAndText01"
  • "TileWidePeekImageAndText02"
  • "TileWidePeekImageCollection01"
  • "TileWidePeekImageCollection02"
  • "TileWidePeekImageCollection03"
  • "TileWidePeekImageCollection04"
  • "TileWidePeekImageCollection05"
  • "TileWidePeekImageCollection06"
  • "TileWideSmallImageAndText01"
  • "TileWideSmallImageAndText02"
  • "TileWideSmallImageAndText03"
  • "TileWideSmallImageAndText04"
  • "TileWideSmallImageAndText05"
  • "TileWideText01"
  • "TileWideText02"
  • "TileWideText03"
  • "TileWideText04"
  • "TileWideText05"
  • "TileWideText06"
  • "TileWideText07"
  • "TileWideText08"
  • "TileWideText09"
  • "TileWideText10"
  • "TileWideText11"
Not allowed when "Tile.visual" is set.
Windows.Tile.visual object This object has the same structure as "Toast.visual", except adding a contentId field and template names similar to "Tile.template".
Windows.Tile.visual.contentId string Set to a sender-defined string that uniquely identifies the content of the notification. This prevents duplicates in the situation where a large tile template is displaying the last three wide tile notifications.
Windows.Tile.text array An array of strings or "text" objects that will be used according to the template structure. Not allowed when "Tile.visual" is set.
Windows.Tile.image array An array of strings or "image" objects that will be used according to the template structure. Not allowed when "Tile.visual" is set.

System-Set Fields

These fields cannot be set when creating a push notification but will be returned when reading a push notification using the Administration API.

Property Name Value Type Description
Status Number Indicates the current state of the push notification: 10—Pending, 20—Not sent, 30—Sent, 40—Canceled, 100/110—Pending for resending, 120—Re-sent
Locked Boolean This is a system field.
Feedback Object Contains full information about the number of messages that resulted from this push notification.
Feedback.{n} Object Contains information about the number of addressed devices serviced by the indicated vendor (n). 1 = WindowsPhone; 2 = Windows; 3 = Android; 4 = iOS.
Feedback.{n}.Sent Number To how many devices the notification was sent in the sense of being accepted by the vendor. Note that the information is provided by the vendor and does not guarantee actual reception.
Feedback.{n}.Deactivated Number The number of devices whose tokens were reported invalid by the vendor. One possible reason is that the user uninstalled your app.
Feedback.{n}.Failed Number The number of devices that the vendor rejected. Possible reasons include using a certificate for another AppId on iOS or using a wrong server key on Android, among others.
Feedback.LastFeedbackDate Date Date and time when the server lastly collected the feedback information that you are viewing. Uses ISO 8601 format.
Feedback.Sent Number An aggregation of all Sent values from each vendor-specific object (Feedback.{n}.Sent).
Feedback.Deactivated Number An aggregation of all Deactivated values from each vendor-specific object (Feedback.{n}.Deactivated).
Feedback.Failed Number An aggregation of all Failed values from each vendor-specific object (Feedback.{n}.Failed).
Feedback.Total Number The sum of all Sent, Deactivated, and Failed devices.
APIKey String The App ID of the Telerik Platform app.
NextRunDate Date When UseLocalTime is set, indicates when the next portion of notifications will be send. Uses ISO 8601 format.
NextExpirationDate Date When UseLocalTime is set, indicates the expiration date for the next portion of notifications. Uses ISO 8601 format.
CreatedAt Date When was the push notification created. Uses ISO 8601 format.
ModifiedAt Date When was the push notification last modified. Uses ISO 8601 format.
Id String A GUID uniquely identifying the push notification in Telerik Platform
InitialDevicesCount Number The number of all devices found in the database at the time of sending that match the targeting criteria of the push notification.
MessagesScheduledCount Number System field for internal use.
MessageCount Number Deprecated The amount of messages sent. Usually takes a while to aggregate. Only older push notifications will contain it.

See Also

Start a free trial Request a demo
Contact us: +1-888-365-2779
sales@telerik.com
Copyright © 2016-2017, Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.