In order to find a user to whom you need to send a notification, it is possible to specify one or several available identifiers:
The object of a message for the Android platform contains 2 fields:
payload (object) - describes the main content of a notification
options (object) - describes the optional settings of notification delivery
POST
POST
Property
Type
Description
token
string
Push token. If you use push token, all fields with other identifiers will be ignored!
advertisingId
string
Advertising ID
androidId
string
Android ID
serialId
string
Serial ID
userId
string
User id is applicable if an internal identifier (cross-platform user identifier) is used in your app.
devtodevId
number
Numeric user identifier in devtodev database.
Property
Type
Description
title
string
A short string describing the purpose of a notification.
text
string
The text of an alert message.
data
object
Optional if notification is not hidden. You can pass custom parameters with messages and use them within an app. For instance, you can activate advertising campaign or any other functionality for a user who has received this message.
Example:
"data": {
"my_key": "value",
"my_another_key": "15"
}
small_icon
string
Optional. You may use an icon from resources of your app. You should use resource name of the icon in this field.
color
string
Optional. The parameter recolors the small icon of an app displayed in a notification in the specified color ("#RRGGBB"). This N parameter on Android also recolors the name of an app and texts on notification buttons.
Example:
"color": "#ff0000"
icon
string
Optional. Use the URL to a notification icon or a resource name.
image
string
Optional. The value is image URL. Images should be ≤ 450dp wide, ~2:1 aspect. The image will be center cropped.
sound
string
Optional. A media file to play in place of a default sound. If a sound file doesn’t exist or default is specified as the value, the default notification sound is played. The audio must be in one of the audio data formats that are compatible with system sounds. Supports “default” or the filename of a sound resource bundled in an app. Android sound files must reside in /res/raw/ If the option is not used, a notification comes silently.
badge
int
Optional. This property was added in Android O. The value of the badge on the home screen app icon. If not specified, the badge is not changed. If set to 0, the badge is removed.
vibration
boolean
Optional. In case of "true" during notification delivery a device will vibrate (if permission VIBRATION is received)
led_color
string
Optional. LED hex color ("#RRGGBB"), a device will do its best approximation.
Example:
"led_color": "#ff0000"
action
object
Optional. The action after a click on the body of a notification. By default, a click opens an app. It is also possible to perform the following actions:
deeplink (string) - Direct a user to a specific resource either within your app or on the web.
url (string) - Open a web page in a mobile browser, or any valid device-level URL such as Google Play or app protocol links.
share (string) - The Share Action drives a user to share your message when they interact with your push notification.
Examples:
"action": {
"url": "http://www.domain.com"
}
"action": {
"deeplink": "your-url-scheme://host/path"
}
"action": {
"share": "Happy holidays!"
}
interactive
object
Optional. It is possible to specify an array of notification buttons in an “interactive” object. Each button should contain the following properties:
id (string) - The button identifier. It is transferred to an app.
text (string) - A text on a button
handling (string) - The type of processing
background - The button closes a notification. The parameters of a notification are transferred to an app, but an app does not open. It is impossible to tie an action to a button in this regime.
foreground - The button opens an app. The parameters of a notification are transferred to an app, but an app does not open. It is possible to tie an action to a button in this regime. The list of actions and the principle is analogical to actions with the body of a message.
Example:
"interactive": {
"buttons": [{
"id": "accept",
"text": "Accept",
"handling":"foreground",
"action": {
"url": "http://www.domain.com/accept"
},
{
"id": "decline",
"text": "Decline",
"handling":"background"
}]
}
Property
Type
Description
hidden
boolean
Switching the notification to the hidden mode. If “true” - a notification will not be displayed to a user, but will be transferred to an app. Such a message must not contain any properties except data in the “payload” object.
priority
string
Optional. The priority of a notification. Default value is "normal". Specify one of the following values:
high" – GCM attempts to deliver high priority messages immediately allowing the GCM service to wake a sleeping device when possible and open a network connection to your app server. Apps with instant messaging, chat, or voice call alerts, for example, generally need to open a network connection and make sure GCM delivers the message to the device without delay. Set high priority only if the message is time-critical and requires the user’s immediate interaction, and beware that setting your messages to high priority contributes to a battery drain more compared to normal priority messages.
"normal" — This is the default priority for message delivery. Normal priority messages won't open network connections on a sleeping device, and their delivery may be delayed to preserve a battery. For less time-sensitive messages (such as notifications of new email or other data to sync) choose normal delivery priority.
expire
number
This option identifies the date when a notification is no longer valid and can be discarded. It is possible to use either relative time in seconds passed since the moment of sending, or specify an exact date in UNIX epoch format expressed in seconds (UTC).
Default value is 7 days (604800 seconds) after sending. Max. relative value for Android platform is 2 419 200 seconds (4 weeks).
Keep in mind that an "expire" value of 0 means messages that can't be delivered immediately will be discarded. However, as long as such messages are never stored, this provides the best latency for sending notifications.
collapse_key
string
Optional. Notifications are not collapsible by default.
If multiple messages are sent with this key, the most recent message will suppress all previous unread messages with the same key.
Collapsible messages are a better choice from a performance standpoint provided your application doesn't need to use non-collapsible messages. However, if you use collapsible messages, remember that GCM only allows a maximum of 4 different collapse keys to be used by the GCM connection server per registration token at any given time. You must not exceed this number, or it could cause unpredictable consequences.
channel_id
string
Optional. The notification's channel id (this property was added in Android O). The app must create a channel with this ID before any notification with this key is received. If you don't send this key in the request, or if the channel id provided has not yet been created by your app, devtodev SDK uses the channel id specified by default ("channel_id": "_devtodev" - name: General notifications).
badge_icon_type
int
Optional. This property was added in Android O (API level 26). 0 - Default. If this notification is being shown as a badge, always show as a number. 1 - If this notification is being shown as a badge, use the getSmallIcon() to represent this notification. 2 - If this notification is being shown as a badge, use the getLargeIcon() to represent this notification.
To use Push API you need to have individual User API token, which can be found in the settings of space.
You’ll see the block with User API token on the space settings page only in case if your tariff plan and access rights allow to use devtodev API. You can reset User API token or create it again on the same page.
Please attend, if you use several spaces, in every space user has individual User API token.
The request of assignment should be sent to:
Where
user_token - individual User API token of a user. It could be sent with both GET and POST methods.
v1 - the current version of API
Request content is sent with POST method in JSON format.
The body of a request can contain the following properties:
An example of a request for sending a simple notification to an iOS device:
POST
If a request is formed correctly and there are no obstacles for sending a notification to users, an answer is JSON of the following type:
where
audience (number) - the number of users found
successful (number) - the number of successfully sent notifications
erroneous (number) - the number of notifications rejected by the delivery service
error_details (array) - a detailed description of reasons of a delivery fail
In case there is an error in a request, an answer is made in the following format:
where
status_code (number) - a general status of an error
errors (array) - an array of error descriptions
code (number) - the exact code of an error from the table of errors
msg (string) - a brief description of an error
The list of possible errors is given in a table.
Besides the errors listed above, error_details field may contain errors from the connected notification services. You can find descriptions of such errors in documentation for these services:
devtodev Push API supports two different formats of notification sending to Windows operational systems:
Universal format described in this section works on the basis of Legacy tiles and toast schema. It can be used on Windows Phone 8.1, Windows Phone 10, Windows 8.1, Windows 10. It is described by the "win" object.
UWP format - can be used only for Windows 10 and Windows Phone 10. It is described by the "uwp" object.
In order to find a user to whom you need to send a notification, you can specify one or several available identifiers:
Object "windows" can contain two properties :
The property that describes a message can be represented by one of 4 possible objects:
toast (object) - the result of sending is the delivery of toast-notification
raw (object) - sends a hidden toast-notification
tile (object) - changes tile content of an app
badge (object) - changes the value of a badge field displayed in a tile of an app
The property that describes additional parameters of a message represented by the object “options”. Optional.
Example
Example
Example
Example
Additional settings of notification delivery and display ("options" object)
devtodev Push API supports two different formats of notification sending to Windows operational systems:
UWP format described in this section can be used only for Windows 10 and Windows Phone 10. It is described by the "uwp" object.
The universal format works on a basis of Legacy tiles and toast schema. It can be used for Windows Phone 8.1, Windows Phone 10, Windows 8.1, Windows 10. It is described by the "windows" object.
Use this object (“uwp”) if your clients are users of OS Windows 10 and Windows Phone 10 only. With the help of this method it is possible to realize more opportunities offered by Windows 10.
In order to find an addressee to whom you need to send a notification, it is possible to specify one or several available identifiers:
Object "uwp" can contain 2 properties:
The property that describes a message can be represented by one of 4 possible objects: - toast (object) - the result of sending is the delivery of toast-notification - raw (object) - sends a hidden toast-notification - tile (object) - changes the tile content of an app - badge (object) - changes the value of a badge field displayed on a tile
The property that describes additional parameters of a message is represented by the object “options”. Optional.
Example
In UWP format every of tile’s size must be described separately, therefore, the object “tile” can contain up to 4 properties:
small
medium
wide
large (only for desktop)
Each of these sizes is described by an object with the following properties:
Example
Example
Example
In order to find a user to whom you need to send a notification, it is possible specify one or several available identifiers:
The object of a message for the iOS platform contains 2 fields:
payload (object) - describes the main content of a notification
options (object) - describes the optional settings of notification delivery
The text on the buttons, which are on the list of templates, is translated into N languages and displayed to users individually according to the location of a device.
POST
POST
Property
Type
Description
user_token
string
Required. An individual user API token. It can be found on the space settings page. It is possible to send it with both POST and GET methods.
app_id
string
Required. An application identifier. It can be found in the application’s settings in the Integration section. Required.
campaign_tag
string
Optional. The name of a campaign. The grouping of statistics for the assessment of the efficiency of a campaign is made by the name of a campaign. The API Stats report can be found in the Push section.
pack_id
string
Optional. The unique identifier of a request. It is specified by a developer. It is used for the filtering of repeated sendings of identical requests in case of the loss of connection, etc. Requests with the same identifier can't be repeated during 10 minutes after their sending.
audience
array
Required. An array of mailing audience. The element of an array is an object with an individual for every platform set of user identifiers. It is allowed to specify several known identifiers for one user. The maximum number of elements of an array is 1000.
The lists of available identifiers can be found in the description to each platform.
ios
object
An object containing a notification and its properties for the iOS platform.
android
object
An object containing a notification and its properties for the Android platform.
win
object
An object containing a notification and its properties for the Windows platform. Use this object for any version of Windows (Windows Phone 8.1, Windows Phone 10, Windows 8.1, Windows 10).
uwp
object
An object containing a notification and its properties for the Windows 10 / WP 10. Don’t use this object for sending to other versions of Windows.
Status code
Code
Value of "msg" field
Error description
500
1
Unknown Error
Unknown error. Please contact devtodev technical support.
400
2
Request body is empty
The empty body of the request. There is no POST data in the request.
400
3
Malformed json
JSON error in the body of the request. Fix the formatting error.
400
4
Field not found: %field_name%
An obligatory field can not be found. You need to complete the request with this field.
400
6
Invalid app id %app id value%
The requested project can not be found. An unknown application. This error can arise when a user makes a mistake with an app ID or when an application with this ID has been removed.
401
11
Authorization error. Wrong user token %user_token value%
Authorization error. The set token is wrong. “User_token” field. User API token.
401
12
Authorization error. User_token is not set.
Authorization error. “User_token” field is absent. User API token should be set either as a parameter in GET string of the request or in POST body of the request.
403
13
Access denied. You have no access to the app %app id value%
The error of access. User has no access to this application.
403
14
Access denied. You have no access to the report file %file id value%
The error of access. User has no access to this file. This error can arise if you have to access the application used in a previously created request.
403
15
Access denied. You have no access to API.
The error of access. No access to User API token. This error can arise when access rights have been changed (as a consequence of changing a user role or tariff plan)
403
23
Access denied. You have no access to Push API.
The error of access. This error can arise when you have no rights to Push API for your user role or tariff plan.
400
24
Push service is not enabled in an application settings.
Push service is disabled. Enable the service on the settings page of an app.
400
25
The devtodev SDK is not integrated with the application you specified
The SDK is not integrated
400
26
No push token has been received from the devtodev SDK integrated with the app you specified. Please make sure the SDK is integrated correctly.
No push token has been received from the devtodev SDK integrated with the app you specified. Please make sure the SDK is integrated correctly.
400
27
The audience array should not contain more than 1000 elements.
The audience array contains more than 1000 elements. Reduce the number of users in one request.
400
28
Unexpected value for field %field%. Received value: %value%. Expected values: %values%.
There is an unexpected value for the field. Use the recommendation and correct the request.
400
29
Unexpected field %field%
The request contains the field not specified in the documentation. The field must be excluded from the request.
400
30
Invalid value for field %field%. Received value: %value%. Expected: %description%
Invalid value has been attributed to the field. Use the recommendation and correct the request.
400
31
Notification payload size limit exceeded.
Reduce the payload size.
400
32
The sending was blocked. The request with the %pack_id% identifier has already been sent during previous 10 minutes.
Requests with the same identifier can't be repeated during 10 minutes after their sending.
400
33
The requested users have not been found, or there have been no push-token received from them.
The requested users have not been found, or there have been no push-token received from them.
Property
Type
Description
token
string
Push token. If you use push token, all fields with other identifiers will be ignored!
advertisingId
string
Advertising ID
serialId
string
Hardware serial number
userId
string
User id is applicable if an internal identifier (cross-platform user identifier) is used in your app.
devtodevId
number
Numeric user identifier in devtodev database.
Property
Type
Description
title
string
Required. A short string describing the purpose of a notification.
text
string
Required. Main text of a notification message .
text2
string
Optional. Additional text of a notification.
data
object
Optional. You can pass custom parameters with messages and use them within an app. For instance, you can activate advertising campaign or any other functionality for the user who has received this message.
Example:
"data": {
"my_key": "value",
"my_another_key": "15"
}
icon
string
Optional. To replace the application icon (that shows up on the top left corner of the toast) use the URL or the resource name.
Any toast shown on Windows Phone 8.1 does not display the images (the app icon only). In Windows 10 the image is expressed using the URI of the image source, using one of these protocol handlers:
A web-based image: http:// or https://
An image included in the app package: ms-appx:///
An image saved to local storage: ms-appdata:///local/
A local image (Only supported for desktop apps.): file:///
sound
string
Optional. A media file to play in place of a default sound. If the option is not used, a notification comes silently. This property can have one of the following string values:
Default
IM
Reminder
SMS
Looping.Alarm
Looping.Alarm2
Looping.Alarm3
Looping.Alarm4
Looping.Alarm5
Looping.Alarm6
Looping.Alarm7
Looping.Alarm8
Looping.Alarm9
Looping.Alarm10
Looping.Call
Looping.Call2
Looping.Call3
Looping.Call4
Looping.Call5
Looping.Call6
Looping.Call7
Looping.Call8
Looping.Call9
Looping.Call10
On mobile platform, this property can also contain the path to a local audio file, with one of the following prefixes:
ms-appx:///
ms-appdata:///
action
object
Optional. Available for Windows 10 and WP 10 only. Action after a click on the body of a notification. By default, a click simply opens an app. It is also possible to perform the following actions:
deeplink (string) - Direct the user to a specific resource, either within your app or on the web.
url (string) - Open a web page in a mobile browser, or any valid device-level URL such as Windows Store or app protocol links.
share (string) - The Share Action drives a user to share your message when they interact with your push notification.
Examples:
"action": {
"url": "http://www.domain.com"
}
"action": {
"deeplink": "your-url-scheme://host/path"
}
"action": {
"share": "Happy holidays!"
}
interactive
object
Optional. Available for Windows 10 and WP 10 only. It is possible to specify an array of notification buttons in the “interactive” object. Each button must contain the following properties:
id (string) - Button identifier. It is transferred to an app
text (string) - Text on a button
handling (string) - The type of processing
background - A button closes an app. Notification parameters are transferred to an app, but an app doesn’t open. It is impossible to tie an action to a button in this regime.
foreground - A button opens an app. Notification parameters are transferred to an app. It is possible to tie an action to a button in this regime. The list of actions and the principle is analogical to actions with the body of a message.
Example:
"interactive": {
"buttons": [{
"id": "accept",
"text": "Accept",
"handling":"foreground",
"action": {
"url": "http://www.domain.com/accept"
},
{
"id": "decline",
"text": "Decline",
"handling":"background",
}]
}
Property
Type
Description
data
object
Required. You can pass custom parameters with messages and use them within an app. For instance, you can activate advertising campaign or any other functionality for user who has received this message.
Example:
"data": {
"my_key": "value",
"my_another_key": "15"
}
badge
string
Optional. A number from 1 to 99. A value of 0 is equivalent to the glyph value "none" and will clear a badge.
Instead of a number, a badge can display one of a non-extensible set of status glyphs:
activity
none
alarm
alert
attention
available
away
busy
error
newMessage
paused
playing
unavailable
It is also possible to send values incrementing or decrementing the current value in a “+2”, “-1” format. In case the previous value was the glyph or 0, the value will be increment. Decrement does not influence the zero value and the glyph.
Property
Type
Description
text1
string
First string on the tile.
with_header
boolean
Set True to mark "text1" field as a heading to show it larger.
text2
string
Second string on the tile.
text3
string
Third string on the tile.
text4
string
Fourth string on the tile.
image
string
Optional.Application-relative or Internet URI of the image.
Example:
"red.jpg" (if image is stored in an app’s installation directory or local storage folder)
"http://my.domain.com/img/red.jpg" (for Internet URIs).
We recommend using images with size 336 pixels by 336 pixels.
Important Note:
If you need to use remote Internet URIs for Tile images, you must take the following steps:
Ensure the remote image file size is less than 150 KB.
Ensure the image can be downloaded in 60 seconds or less.
Property
Type
Description
badge
string
A number from 1 to 99. A value of 0 is equivalent to the glyph value "none" and will clear a badge.
Instead of a number, a badge can display one of a non-extensible set of status glyphs:
activity
none
alarm
alert
attention
available
away
busy
error
newMessage
paused
playing
unavailable
Property
Type
Description
expire
number
This option identifies the date when the tile or toast is no longer valid and can be discarded. It is possible to use either relative time in seconds passed since sending, or to specify an exact date in UNIX epoch format date expressed in seconds (UTC). Default value is 7 days (604800 seconds) after sending.
Property
Type
Description
token
string
Push token. If you use push token, all fields with other identifiers will be ignored!
advertisingId
string
Advertising ID
serialId
string
Hardware serial number
userId
string
User id is applicable if an internal identifier (cross-platform user identifier) is used in your app.
devtodevId
number
Numeric user identifier in devtodev database.
Property
Type
Description
scenario
string
Optional. Available values: "default", "alarm", "reminder", "incomingCall". Default value is "default". You do not need this unless your scenario is to pop an alarm, reminder, or incoming call. Do not use this just for keeping your notification persistent on screen.
title
string
Required. A short string describing the purpose of a notification.
text
string
Required. Main text of a notification.
text2
string
Optional. Additional text of a notification.
data
object
Optional if notification is not hidden. You can pass custom parameters with messages and use them within an app. For instance, you can activate advertising campaign or any other functionality for user who has received this message.
Example:
"data": {
"my_key": "value",
"my_another_key": "15"
}
icon
string
Optional. To replace the application icon (that shows up on the top left corner of the toast) use the URL or the resource name.
In Windows 10 the image is expressed using the URI of the image source, using one of these protocol handlers:
A web-based image: http:// or https://
An image included in the app package: ms-appx:///
An image saved to local storage: ms-appdata:///local/
A local image (Only supported for desktop apps.): file://
image
string
Optional. Image inside the toast body, below the text. Use the URL or the resource name.
sound
string
Optional. The media file to play in place of the default sound. If the option is not used, the notification comes silently. This property can have one of the following string values:
Default IM
Reminder
SMS
Looping.Alarm
Looping.Alarm2
Looping.Alarm3
Looping.Alarm4
Looping.Alarm5
Looping.Alarm6
Looping.Alarm7
Looping.Alarm8
Looping.Alarm9
Looping.Alarm10
Looping.Call
Looping.Call2
Looping.Call3
Looping.Call4
Looping.Call5
Looping.Call6
Looping.Call7
Looping.Call8
Looping.Call9
Looping.Call10
On mobile platform this property can also contain the path to a local audio file with one of the following prefixes:
ms-appx:///
ms-appdata:///
action
object
Optional. Action after a click on the body of a notification. By default, a click simply opens an app. It is also possible to perform the following actions:
deeplink - Direct the user to a specific resource, either within your app or on the web.
url - Open a web page in a mobile browser, or any valid device-level URL such as Windows Store or app protocol links.
share - The Share Action drives a user to share your message when they interact with your push notification.
Examples:
"action": {
"url": "http://www.domain.com"
}
"action": {
"deeplink": "your-url-scheme://host/path"
}
"action": {
"share": "Happy holidays!"
}
interactive
object
Optional. It is possible to specify an array of notification buttons in the “interactive” object. Each button must contain the following properties:
id (string) - Button identifier. It is transferred to an app
text (string) - Text on a button
handling (string) - The type of processing
background - A button closes an app. Notification parameters are transferred to an app, but an app doesn’t open. It is impossible to tie an action to a button in this regime.
foreground - A button opens an app. Notification parameters are transferred to an app, but an app doesn’t open. It is possible to tie an action to a button in this regime. The list of actions and the principle is analogical to actions with the body of a message.
Example:
"interactive": {
"buttons": [{
"id": "accept",
"text": "Accept",
"handling":"foreground",
"action": {
"url": "http://www.domain.com/accept"
},
{
"id": "decline",
"text": "Decline",
"handling":"background",
}]
}
Property
Type
Description
content
array
As long as tile’s content is dynamic, it is described by an array, the elements of which can be objects describing either text strings or illustrations.
Text element object properties:
text (string) - Required. The displayed string.
wrap (boolean) - Optional. By default, text doesn't wrap and will continue off the edge of the tile. Set true to set text wrapping on a text element.
style (string ) - Optional. Styles control the font size, color, and weight of text elements. There is a number of available styles including a "subtle" variation of each style that sets the opacity to 60%, which usually makes the text color a shade of light gray. Basic text styles:
caption (12 effective pixels height, regular weight)
body (15 epx, regular)
base (15 epx, semibold)
subtitle (20 epx, regular)
title (24 epx, semilight)
subheader (34 epx, light)
header (46 epx, light)
Numeral text style variations: (These variations reduce the line height so that content above and below come much closer to the text.)
titleNumeral
subheaderNumeral
headerNumeral
Subtle text style variations: (Each style has a subtle variation that gives the text a 60% opacity, which usually makes the text color a shade of light gray.)
captionSubtle
bodySubtle
baseSubtle
subtitleSubtle
titleSubtle
titleNumeralSubtle
subheaderSubtle
subheaderNumeralSubtle
headerSubtle
headerNumeralSubtle
Image element object properties
image (string) - Required. Image URI
remove_margin (boolean ) - Optional. By default, inline images have an 8-pixel margin between any content above or below the image. Set true to remove margin.
align (string) - Optional. Images can be set to align "left", "center", or "right". This will also cause images to display at their native resolution instead of stretching to fill width.
crop (string ) - Optional. Default value is "none". Images can be cropped into a circle in case of "circle" value.
placement (string) - Optional. You can specify an image that "peeks” in from the top of a tile or set a "background" image.
Group element object properties
group (array) - Required. Array of subgroup elements.
Subgroup element object (used inside groups only)
subgroup (array) - Required. Array of text or/and image elements.
branding
object
You can control the branding on the bottom of a live tile (the display name and corner logo) by using this property. Branding object properties:
type (string) - You can choose to display "none", only the "name", only the "logo", or both with "nameAndLogo". Windows Mobile doesn't support a corner logo, so "logo" and "nameAndLogo" default to"name" on mobile.
display_name (string) - Optional. You can override the display name of a notification by entering the text string of your choice.
v_align
string
You can control the vertical alignment of content on your tile by using this property. By default, everything is vertically aligned to the "top", but you can also align content to the "bottom" or "center".
overlay
number
Optional. You can set a black overlay on your background image using this property, which accepts integers from 0-100 with 0 being no overlay and 100 being full black overlay.
If you don't specify an overlay, the background image opacity defaults to 20% and the peek image opacity defaults to 0%.
Property
Type
Description
data
object
Required. You can pass custom parameters with messages and use them within an app. For instance, you can activate advertising campaign or any other functionality for user who has received this message.
Example:
"data": {
"my_key": "value",
"my_another_key": "15"
}
badge
string
Optional. A number from 1 to 99. A value of 0 is equivalent to the glyph value "none" and will clear a badge.
Instead of a number, a badge can display one of a non-extensible set of status glyphs:
activity
none
alarm
alert
attention
available
away
busy
error
newMessage
paused
playing
unavailable
It is also possible to send values incrementing or decrementing the current value in a “+2”, “-1” format. In case the previous value was the glyph or 0, the value will be increment. Decrement does not influence the zero value and the glyph.
Property
Type
Description
badge
string
A number from 1 to 99. A value of 0 is equivalent to the glyph value "none" and will clear a badge.
Instead of a number a badge can display one of a non-extensible set of status glyphs:
activity
none
alarm
alert
attention
available
away
busy
error
newMessage
paused
playing
unavailable
Property
Type
Description
token
string
Push token. If you use a push token, all fields with other identifiers will be ignored!
idfa
string
Ad identifier IDFA
idfv
string
Device identifier under vendor IDFV
userId
string
User id is applicable if an internal identifier (cross-platform user identifier) is used in your app
devtodevId
number
Numeric user identifier in devtodev database.
Property
Type
Description
title
string
Optional. A short string describing the purpose of a notification. Apple Watch displays this string as a part of the notification interface. This string is displayed only briefly and should be crafted so that it can be understood quickly. This key was added in iOS 8.2.
text
string
The text of an alert message. Required if a notification is not hidden.
title-loc-key
string
Optional. The 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 title-loc-args array. See Localized Formatted Strings for more information. This key was added in iOS 8.2.
title-loc-args
string
Optional. Variable string values to appear in place of format specifiers in title-loc-key. See Localized Formatted Strings for more information. This key was added in iOS 8.2.
action-loc-key
string
Optional. If 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.
loc-key
string
Optional. The key to an alert message string in a Localizable.strings file for the current localization (which is set by the user’s language preferences). The key string can be formatted with %@ and %n$@ specifiers to take the variables specified in the loc-args array. See Localized Formatted Strings for more information.
loc-args
array
Optional. Variable string values to appear in place of format specifiers in loc-key. See Localized Formatted Strings for more information.
launch-image
string
Optional. The filename of an image file in the app bundle, with or without the filename extension. The image is used as a 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.
data
object
Optional if notification is not hidden. You can pass custom parameters with messages and use them within an app. For instance, you can activate advertising campaign or any other functionality for the user who has received this message.
Example:
"data": {
"my_key": "value",
"my_another_key": 15
}
badge
number
Optional. The 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.
sound
string
Optional. The 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 Preparing Custom Alert Sounds for details.
attachment
object
Optional. Available from devtodev iOS SDK 1.9, Cordova SDK 1.9, Unity SDK 2.3, UE4 SDK 1.9, Air SDK 1.8 Added in iOS 10. The possibility to attach images, videos, audio, and GIFs is available in iOS 10. Specify the type of an attachment ("image", "audio" or "video") and URL that leads to a media file. Attention, iOS uses only “https” protocol.
Example:
"attachment": {
"type": "image",
"url": "https://domain.com/pic.gif"
}
action
object
Optional. Available from devtodev iOS SDK 1.9, Cordova SDK 1.9, Unity SDK 2.3, UE4 SDK 1.9, Air SDK 1.8 The action after a click on the body of a notification. By default, a click simply opens an app. It is also possible to perform the following actions:
deeplink (string) - Direct the user to a specific resource, either within your app or on the web.
url (string) - Open a web page in a mobile browser, or any valid device-level URL such as App Store or app protocol links.
share (string) - The Share Action drives a user to share your message when they interact with your push notification.
Examples:
"action": {
"url": "http://www.domain.com"
}
"action": {
"deeplink": "your-url-scheme://host/path"
}
"action": {
"share": "Happy holidays!"
}
interactive
object
Optional. Available from devtodev iOS SDK 1.9, Cordova SDK 1.9, Unity SDK 2.3, UE4 SDK 1.9, Air SDK 1.8 It is possible to specify one of the existing button templates in an “interactive” object, as well as assign the necessary actions to template buttons. It is possible to assign additional actions only to the button that opens an app. The same set of actions is available: deeplink, url and share. The list of accessible button templates is below in the text.
Example:
"interactive": {
"template": "dtd_accept.open_decline.dismiss",
"buttons": [{
"id": "accept",
"action": { "url": "http://www.domain.com/accept"
}
}]
}
Property
Type
Description
sandbox
boolean
Default value is false ("Production" gateway). Set to true if you need to send notification through the "Sandbox" gateway (for builds signed with a developer certificate).
hidden
boolean
Switching a notification to the hidden mode. If “true” - a notification will not be displayed to a user, but will be transferred to an app. Such a message must not contain any properties except “data” in the “payload” object.
Including this key and value means that when your app is launched in the background or resumed, application:didReceiveRemoteNotification:fetchCompletionHandler: is called
priority
string
Optional. The priority of a notification. Default value is "normal". Specify one of the following values:
"high" – Send a push message immediately. Notifications with this priority must trigger an alert, sound, or badge on a target device. It is an error to use this priority for a push notification that contains only the content-available key.
"normal" — Send a push message at a time that takes into account power considerations for a device. Notifications with this priority might be grouped and delivered in bursts. They are throttled, and in some cases are not delivered.
expire
number
This option identifies the date when the notification is no longer valid and can be discarded. It is possible to use either relative time in seconds passed since the moment of sending, or to specify the exact date in UNIX epoch format date expressed in seconds (UTC).
Default value is 7 days (604800 seconds) after sending.
If this value is nonzero, APNs stores a notification and tries to deliver it at least once repeating the attempt as needed if it is unable to deliver a notification for the first time. If the value is 0, APNs treats the notification as if it expires immediately and does not store the notification or attempt to redeliver it.
collapse_key
string
Multiple notifications with the same collapse identifier are displayed to a user as a single notification. The value should not exceed 64 bytes.
Name
Description
Template ID
Button 1
Button 2
Label
id
Label
id
Yes or No (Open an app)
Yes option takes user into an app. No dismisses the notification.
dtd_yes.open_no.dismiss
Yes
yes
No
no
Yes or No (Dismiss notification)
Yes and No options dismiss the notification when clicked without taking a user into an app.
dtd_yes.dismiss_no.dismiss
Yes
yes
No
no
Accept or Decline (Open the app)
Accept option takes a user into an app. No dismisses a notification.
dtd_accept.open_decline.dismiss
Accept
accept
Decline
decline
Accept or Decline (Dismiss notification)
Yes and No options dismiss a notification when clicked without taking a user into an app.
dtd_accept.dismiss_decline.dismiss
Accept
accept
Decline
decline
Shop Now
Shop Now takes user into an app. Should be a different location from a notification action.
dtd_shop_now.open
Shop Now
shop_now
Buy Now
Buy Now takes user into an app. Should be a different location from a notification action.
dtd_buy_now.open
Buy Now
buy_now
Tell me more
Deep link to more details about a specific offer or program
dtd_more_info.open
Tell me more
more_info
Download
Download deep links users directly to media e.g. wallpaper images, apps, music downloads, file downloads, etc.
dtd_download.open
Download
download
Share
Pass sharing text through to native OS apps like Facebook and Twitter using the Share action.
dtd_share.open
Share
share
Download or Share
Download deep links users directly to media e.g. wallpaper images, apps, music downloads, file downloads, etc. Share the same media socially.
dtd_download.open_share.open
Download
download
Share
share
Shop Now or Share
Shop Now takes a user into an app; should be a different location from a notification action.
dtd_shop_now.open_share.open
Shop Now
shop_now
Share
share
Buy Now or Share
Buy Now takes a user into an app; should be a different location from a notification action.
dtd_buy_now.open_share.open
Buy Now
buy_now
Share
share
Like or Dislike
Both options take a user into an app.
dtd_like.open_dislike.open
Like
like
Dislike
dislike
Like or Dislike
Like option takes user into an app. Dislike dismisses a notification.
dtd_like.open_dislike.dismiss
Like
like
Dislike
dislike
Like
Option takes a user into an app.
dtd_like.open
Like
like
Like and Share
Capture user sentiment by allowing users to like a message or share it. Both options take user into an app.
dtd_like.open_share.open
Like
like
Share
share
Add
Add an item: most often a wallet pass or card to your digital Wallet.
dtd_add.open
Add
add
Save and No
Save something for future reference.
dtd_save.open
Save
save
Rate now
Drive users to rate an app in the app store by deep linking from this button.
dtd_rate.open
Rate now
rate
Search
Deep link to a search functionality within an app
dtd_search.open
Search
search
Book now
Deep link to booking flow within an app.
dtd_book.open
Book now
book
