Create Notification
/mobile/system/notifications/notifications/
Creates a notification.
If you are using BASIC authorization, and the notification is for a different mobile backend, then the Oracle-Mobile-Backend-ID
header must identify that mobile backend, and not the backend that your app is associated with.
Permissions
To access this operation, you must be a team member with the MobileEnvironment_Notifications
role.
Request
- application/json
object
User-entered notification
-
object Notification properties
Title:
Notification properties
-
object Notification payload
Title:
Notification payload
The payload to send. A notification can specify any combination of message, template, and unified payload. When selecting the most appropriate payload for a provider, the service uses the unified payload if it exists, then the template, if it exists, then the message (in that order).
object
Notification properties
-
notificationTokens(optional):
array notificationTokens
Minimum Number of Items:
1
Maximum Number of Items:1000
Unique Items Required:true
Select devices to send the notification to by `notificationToken`. -
platform(optional):
string
Title:
Supported platforms
Allowed Values:[ "IOS", "ANDROID", "WINDOWS", "WEB" ]
-
provider(optional):
string
Title:
Supported notification providers
Allowed Values:[ "APNS", "GCM", "FCM", "WNS", "SYNIVERSE" ]
-
sendOn(optional):
string
Title:
Short date and time
Pattern:([0-9][0-9][0-9][0-9])-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])(T([0-1][0-9]|2[0-3]):([0-5][0-9]))+Z
Complete date plus hours and minutes in W3C date-time format (YYYY-MM-DD[Thh:mm]Z). -
tag(optional):
string
User-defined tag that you use to categorize notifications.
-
users(optional):
array users
Minimum Number of Items:
1
Unique Items Required:true
Select devices to send the notification to by `user`.
object
Notification payload
-
message(optional):
string
A simple message string. This will be used to create the payload. The maximum payload size depends on the provider. For APNS, FCM and GCM the payload size limit is 4096 bytes, for WNS the limit is 5000 bytes, and for Syniverse the limit is 1000 bytes.
-
payload(optional):
object Unified payload for notification providers
Title:
Unified payload for notification providers
-
template(optional):
object Template reference
Title:
Template reference
Name and parameters for a template from which to create the payload
array
1
1000
true
array
1
true
object
Unified payload for notification providers
-
services:
object Notification payloads for specific providers
Title:
Notification payloads for specific providers
object
Template reference
-
name:
string
The template name.
-
parameters(optional):
object parameters
The template parameters. The required parameters are defined by the template.
object
Notification payloads for specific providers
-
apns(optional):
object apns
If specified, this payload is used for notifications sent using APNS. This object must conform to APNS requirements.
-
fcm(optional):
object fcm
If specified, this payload is used for notifications sent using FCM. An
fcm
object can contain either anotification
object or adata
object. Anotification
object has a predefined set of user-visible keys described in the FCM documentation. Adata
object has custom key-value pairs. -
gcm(optional):
object gcm
If specified, this payload is used for notifications sent using GCM. This object can contain arbitrary JSON properties.
-
syniverse(optional):
object Syniverse payload
Title:
Syniverse payload
-
wns(optional):
object WNS payload
Title:
WNS payload
object
object
fcm
object can contain either a notification
object or a data
object. A notification
object has a predefined set of user-visible keys described in the FCM documentation. A data
object has custom key-value pairs.object
object
Syniverse payload
-
body:
string
The message to send as an SMS message.
object
WNS payload
-
badge(optional):
object Badge value or glyph
Title:
Badge value or glyph
-
raw(optional):
object Raw payload
Title:
Raw payload
Specifies a raw payload. This is any arbitrary JSON object. -
tile(optional):
object Base tile element
Title:
Base tile element
Base tile element, which contains a single visual element. -
toast(optional):
object Base toast element
Title:
Base toast element
Base toast element, which contains at least a single visual element.
object
Badge value or glyph
-
value:
string
Either a numeric value or a string value that specifies a predefined badge glyph.
-
version(optional):
integer
The version of the badge XML schema that this particular payload was developed for.
object
Raw payload
object
Base tile element
-
visual:
object Binding child elements
Title:
Binding child elements
object
Base toast element
-
audio(optional):
object Sound to play
Title:
Sound to play
Specifies a sound to play when a toast is displayed. This element also allows you to mute toast audio. -
commands(optional):
object Scenario commands
Title:
Scenario commands
Specifies that the toast indicates an incoming call or an alarm, with appropriate commands associated with each scenario. -
duration(optional):
string
The amount of time the toast should display.
-
launch(optional):
string
A string that is passed to the application when it is activated by the toast. The format and contents of this string are defined by the app for its own use.
-
visual:
object Single binding element that defines a toast
Title:
Single binding element that defines a toast
object
Binding child elements
-
object Child element properties
Title:
Child element properties
-
object Common visual and binding properties
Title:
Common visual and binding properties
object
Child element properties
-
binding(optional):
array binding
Minimum Number of Items:
1
Maximum Number of Items:2
Specifies the tile template. Every notification should include one binding element for each supported tile size. -
contentId(optional):
string
Set to a sender-defined string that uniquely identifies the content of the notification.
-
version(optional):
string
The version of the tile XML schema this particular payload was developed for.
object
Common visual and binding properties
-
addImageQuery(optional):
boolean
Set to `true` to allow Windows to append a query string to the image URI supplied in the toast notification.
-
baseUri(optional):
string
A default base URI that is combined with relative URIs in image source attributes.
-
branding(optional):
string
The form that the tile should use to display the app's brand.
-
lang(optional):
string
The target locale of the XML payload, specified as a BCP-47 language tag such as `en-US` or `fr-FR`.
array
1
2
-
Array of:
object Toast template
Title:
Toast template
object
Toast template
-
object Toast template properties
Title:
Toast template properties
-
object Common visual and binding properties
Title:
Common visual and binding properties
object
Toast template properties
-
fallback(optional):
string
For backward compatibility, a template to use if the primary template isn't found.
-
image(optional):
array image
Minimum Number of Items:
0
Specifies an image to use in the toast template. -
template(optional):
string
One of the provided templates on which to base the toast.
-
text(optional):
array text
Minimum Number of Items:
1
Specifies text to use in the toast template.
array
0
-
Array of:
object Image to use in a toast or tile template
Title:
Image to use in a toast or tile template
array
1
object
Image to use in a toast or tile template
-
addImageQuery(optional):
boolean
Set to `true` to allow Windows to append a query string to the image URI supplied in the toast.
-
alt(optional):
string
For users of assistive technologies, a description of the image.
-
src:
string
The URI of the image source.
object
Sound to play
-
loop(optional):
boolean
Set to `true` if the sound should repeat as long as the toast is shown, and `false` to play only once.
-
silent(optional):
boolean
Set to `true` to mute the sound, and `false` to allow the toast sound to play.
-
src(optional):
string
The media file to play in place of the default sound.
object
Scenario commands
-
commands:
array commands
Minimum Number of Items:
1
Specifies the scenario-associated buttons shown in the toast. -
scenario:
string
Specifies the intended use of the notification.
object
Single binding element that defines a toast
-
object Element properties
Title:
Element properties
-
object Common visual and binding properties
Title:
Common visual and binding properties
array
1
-
Array of:
object Scenario button
Title:
Scenario button
Specifies a scenario-associated button shown in a toast. The scenario is specified in the parent commands element.
object
Scenario button
-
arguments(optional):
string
An argument string, which can be passed to the associated app to provide the specifics about the action that it should execute in response to the user action.
-
id:
string
Specifies one command from the system-defined command list.
object
Element properties
-
binding(optional):
object Toast template
Title:
Toast template
-
version(optional):
string
The version of the toast XML schema that this particular payload was developed for.
object
{
"message":"This is the alert message.",
"tag":"Marketing",
"notificationTokens":[
"APNSdeviceToken"
]
}
Response
- application/json
201 Response
-
Location: string
Canonical resource URI for the notification.
object
Stored notification
-
object Stored notification properties
Title:
Stored notification properties
-
object User-entered notification
Title:
User-entered notification
object
Stored notification properties
-
createdOn(optional):
string
Title:
Full date and time
Pattern:([0-9][0-9][0-9][0-9])-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9]).([0-9][0-9][0-9])Z
Complete date plus hours, minutes, seconds, and a decimal fraction of a second in W3C date-time format (YYYY-MM-DDThh:mm.ss.SSSZ). -
deviceCount(optional):
integer
When the `status` is `Sending`, `Sent`, or `Warning`, this is the number of devices that this notification was sent to. Also, under some conditions, this attribute is included when the `status` is `Error`.
-
errorMessage(optional):
string
Message explaining a status of `Error` or `Warning`. If there are multiple associated problems, only the first is shown here.
-
id(optional):
integer
Service-generated identifier.
-
links(optional):
array Relationship links
Title:
Relationship links
Minimum Number of Items:1
Unique Items Required:true
-
platformCounts(optional):
array platformCounts
Minimum Number of Items:
1
Unique Items Required:true
Device counts by platform. -
processedOn(optional):
string
Title:
Full date and time
Pattern:([0-9][0-9][0-9][0-9])-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([0-1][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9]).([0-9][0-9][0-9])Z
Complete date plus hours, minutes, seconds, and a decimal fraction of a second in W3C date-time format (YYYY-MM-DDThh:mm.ss.SSSZ). -
status(optional):
string
Title:
Status values
Allowed Values:[ "New", "Scheduled", "Sending", "Error", "Warning", "Sent" ]
object
User-entered notification
-
object Notification properties
Title:
Notification properties
-
object Notification payload
Title:
Notification payload
The payload to send. A notification can specify any combination of message, template, and unified payload. When selecting the most appropriate payload for a provider, the service uses the unified payload if it exists, then the template, if it exists, then the message (in that order).
array
Relationship links
1
true
-
Array of:
object Link
Title:
Link
array
1
true
-
Array of:
object Device counts for a platform
Title:
Device counts for a platform
object
Link
-
href:
string
A relative URL.
-
rel:
Allowed Values:
[ "self", "canonical", "prev", "next" ]
The type of link.
object
Device counts for a platform
-
deviceCount:
integer
How many devices were selected for this platform.
-
platform:
string
Title:
Supported platforms
Allowed Values:[ "IOS", "ANDROID", "WINDOWS", "WEB" ]
-
successCount:
integer
How many devices were accepted by the underlying notification provider.
object
Notification properties
-
notificationTokens(optional):
array notificationTokens
Minimum Number of Items:
1
Maximum Number of Items:1000
Unique Items Required:true
Select devices to send the notification to by `notificationToken`. -
platform(optional):
string
Title:
Supported platforms
Allowed Values:[ "IOS", "ANDROID", "WINDOWS", "WEB" ]
-
provider(optional):
string
Title:
Supported notification providers
Allowed Values:[ "APNS", "GCM", "FCM", "WNS", "SYNIVERSE" ]
-
sendOn(optional):
string
Title:
Short date and time
Pattern:([0-9][0-9][0-9][0-9])-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])(T([0-1][0-9]|2[0-3]):([0-5][0-9]))+Z
Complete date plus hours and minutes in W3C date-time format (YYYY-MM-DD[Thh:mm]Z). -
tag(optional):
string
User-defined tag that you use to categorize notifications.
-
users(optional):
array users
Minimum Number of Items:
1
Unique Items Required:true
Select devices to send the notification to by `user`.
object
Notification payload
-
message(optional):
string
A simple message string. This will be used to create the payload. The maximum payload size depends on the provider. For APNS, FCM and GCM the payload size limit is 4096 bytes, for WNS the limit is 5000 bytes, and for Syniverse the limit is 1000 bytes.
-
payload(optional):
object Unified payload for notification providers
Title:
Unified payload for notification providers
-
template(optional):
object Template reference
Title:
Template reference
Name and parameters for a template from which to create the payload
array
1
1000
true
array
1
true
object
Unified payload for notification providers
-
services:
object Notification payloads for specific providers
Title:
Notification payloads for specific providers
object
Template reference
-
name:
string
The template name.
-
parameters(optional):
object parameters
The template parameters. The required parameters are defined by the template.
object
Notification payloads for specific providers
-
apns(optional):
object apns
If specified, this payload is used for notifications sent using APNS. This object must conform to APNS requirements.
-
fcm(optional):
object fcm
If specified, this payload is used for notifications sent using FCM. An
fcm
object can contain either anotification
object or adata
object. Anotification
object has a predefined set of user-visible keys described in the FCM documentation. Adata
object has custom key-value pairs. -
gcm(optional):
object gcm
If specified, this payload is used for notifications sent using GCM. This object can contain arbitrary JSON properties.
-
syniverse(optional):
object Syniverse payload
Title:
Syniverse payload
-
wns(optional):
object WNS payload
Title:
WNS payload
object
object
fcm
object can contain either a notification
object or a data
object. A notification
object has a predefined set of user-visible keys described in the FCM documentation. A data
object has custom key-value pairs.object
object
Syniverse payload
-
body:
string
The message to send as an SMS message.
object
WNS payload
-
badge(optional):
object Badge value or glyph
Title:
Badge value or glyph
-
raw(optional):
object Raw payload
Title:
Raw payload
Specifies a raw payload. This is any arbitrary JSON object. -
tile(optional):
object Base tile element
Title:
Base tile element
Base tile element, which contains a single visual element. -
toast(optional):
object Base toast element
Title:
Base toast element
Base toast element, which contains at least a single visual element.
object
Badge value or glyph
-
value:
string
Either a numeric value or a string value that specifies a predefined badge glyph.
-
version(optional):
integer
The version of the badge XML schema that this particular payload was developed for.
object
Raw payload
object
Base tile element
-
visual:
object Binding child elements
Title:
Binding child elements
object
Base toast element
-
audio(optional):
object Sound to play
Title:
Sound to play
Specifies a sound to play when a toast is displayed. This element also allows you to mute toast audio. -
commands(optional):
object Scenario commands
Title:
Scenario commands
Specifies that the toast indicates an incoming call or an alarm, with appropriate commands associated with each scenario. -
duration(optional):
string
The amount of time the toast should display.
-
launch(optional):
string
A string that is passed to the application when it is activated by the toast. The format and contents of this string are defined by the app for its own use.
-
visual:
object Single binding element that defines a toast
Title:
Single binding element that defines a toast
object
Binding child elements
-
object Child element properties
Title:
Child element properties
-
object Common visual and binding properties
Title:
Common visual and binding properties
object
Child element properties
-
binding(optional):
array binding
Minimum Number of Items:
1
Maximum Number of Items:2
Specifies the tile template. Every notification should include one binding element for each supported tile size. -
contentId(optional):
string
Set to a sender-defined string that uniquely identifies the content of the notification.
-
version(optional):
string
The version of the tile XML schema this particular payload was developed for.
object
Common visual and binding properties
-
addImageQuery(optional):
boolean
Set to `true` to allow Windows to append a query string to the image URI supplied in the toast notification.
-
baseUri(optional):
string
A default base URI that is combined with relative URIs in image source attributes.
-
branding(optional):
string
The form that the tile should use to display the app's brand.
-
lang(optional):
string
The target locale of the XML payload, specified as a BCP-47 language tag such as `en-US` or `fr-FR`.
array
1
2
-
Array of:
object Toast template
Title:
Toast template
object
Toast template
-
object Toast template properties
Title:
Toast template properties
-
object Common visual and binding properties
Title:
Common visual and binding properties
object
Toast template properties
-
fallback(optional):
string
For backward compatibility, a template to use if the primary template isn't found.
-
image(optional):
array image
Minimum Number of Items:
0
Specifies an image to use in the toast template. -
template(optional):
string
One of the provided templates on which to base the toast.
-
text(optional):
array text
Minimum Number of Items:
1
Specifies text to use in the toast template.
array
0
-
Array of:
object Image to use in a toast or tile template
Title:
Image to use in a toast or tile template
array
1
object
Image to use in a toast or tile template
-
addImageQuery(optional):
boolean
Set to `true` to allow Windows to append a query string to the image URI supplied in the toast.
-
alt(optional):
string
For users of assistive technologies, a description of the image.
-
src:
string
The URI of the image source.
object
Sound to play
-
loop(optional):
boolean
Set to `true` if the sound should repeat as long as the toast is shown, and `false` to play only once.
-
silent(optional):
boolean
Set to `true` to mute the sound, and `false` to allow the toast sound to play.
-
src(optional):
string
The media file to play in place of the default sound.
object
Scenario commands
-
commands:
array commands
Minimum Number of Items:
1
Specifies the scenario-associated buttons shown in the toast. -
scenario:
string
Specifies the intended use of the notification.
object
Single binding element that defines a toast
-
object Element properties
Title:
Element properties
-
object Common visual and binding properties
Title:
Common visual and binding properties
array
1
-
Array of:
object Scenario button
Title:
Scenario button
Specifies a scenario-associated button shown in a toast. The scenario is specified in the parent commands element.
object
Scenario button
-
arguments(optional):
string
An argument string, which can be passed to the associated app to provide the specifics about the action that it should execute in response to the user action.
-
id:
string
Specifies one command from the system-defined command list.
object
Element properties
-
binding(optional):
object Toast template
Title:
Toast template
-
version(optional):
string
The version of the toast XML schema that this particular payload was developed for.
object
{
"id":1234,
"message":"This is the alert message",
"createdOn":"2014-04-02T12:34:56.789Z",
"status":"New",
"tag":"Marketing",
"notificationTokens":[
"APNSdeviceToken"
],
"links":[
{
"rel":"canonical",
"href":"/mobile/system/notifications/notifications/1234"
},
{
"rel":"self",
"href":"/mobile/system/notifications/notifications/1234"
}
]
}
400 Response
object
Error
-
detail:
string
Message that provides the error details.
-
o:ecid:
string
Execution context ID, which is a unique identifier to correlate events or requests that are associated with the same transaction across several components.
-
o:errorCode:
string
Mobile Cloud Service error code.
-
o:errorDetails(optional):
array o:errorDetails
Minimum Number of Items:
0
List of the issues that cause the error. Included when the error is caused by multiple issues. -
o:errorPath:
string
The relative point in the API path where the error occurred.
-
status:
integer
HTTP status code. See http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html for more details.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
array
0
-
Array of:
object Error Detail
Title:
Error Detail
object
Error Detail
-
instance:
string
The URI to the link that provides more detailed information about the error.
-
o:errorCode:
string
Mobile Cloud Service error code.
-
o:errorPath:
string
The relative point in the API path where the error occurred.
-
title:
string
Summary of the problem.
-
type:
string
The URI to the link that provides details about the HTTP status code.
Examples
This example shows how to use cURL to create notifications by submitting a POST request on the REST resource.
curl -i \
-X POST \
-u team.user@example.com:password \
-d @notifications.json \
-H "Content-Type: application/json; charset=utf-8" \
-H "Oracle-Mobile-Backend-ID: ABCD9278-091f-41aa-9cb2-184bd0586fce" \
http://fif.cloud.oracle.com/mobile/system/notifications/notifications/
Examples of Request Body
Example: Send to a List of Users on a Specified Date and Time
This example shows how to send notifications to a list of users on a specified date and time:
{
"message":"Reminder: Status on incident 1548 is due.",
"tag":"Incidents",
"sendOn": "2015-06-25T6:00Z",
"users":[
"technician14@fif.com",
"technician21@fif.com"
]
}
Example: Send to Users on a Platform
This example shows how to send notifications to users on a mobile platform:
{
"message":"Hi! Our storewide sale is tomorrow.",
"platform":"IOS"
}
Example: Send to a Notification Provider
This example shows how to send notifications to a provider:
{
"message":"Hi! Our storewide sale is tomorrow.",
"provider": "APNS"
}
Example: Send to Devices
This example shows how to send notifications to a specific device ID or a list of device IDs:
{
"message":"Hi! Our storewide sale is tomorrow.",
"notificationTokens":[
"2DD2D2-D2DDG44GD-GDGSDFZS3-3-3DFZSDFDS"
]
}
Example: Use the Unified Payload
This example shows how to use the unified payload to specify a different payload for each supported notification provider. You can define one or more of the following payloads in the services
object:
-
apns
: This payload must conform to APNS requirements. -
fcm
: This payload can contain either anotification
object or adata
object.-
A
notification
object has a predefined set of user-visible keys described in the FCM documentation. For example:"fcm":{ "notification":{ "title":"Sale On Now!", "body":"50% off until Saturday" } }
-
A
data
object has custom key-value pairs. For example:"fcm":{ "data":{ "body":"50% off until Saturday", "Room":"Sale On Now!" } }
-
-
syniverse
: This payload should contain the string to send as a SMS message. -
wns
: This payload must contain a well-formed WNS payload.
{
"payload":{
"services":{
"apns":{
"aps":{
"alert":"This is my alert message"
}
},
"fcm":{
"notification":{
"body":"This is my alert message"
}
},
"syniverse":{
"mcs":{
"alert":{
"body":"This is my alert message"
}
}
},
"wns":{
"toast":{
"visual":{
"binding":{
"template":"ToastText01",
"text":[
"This is my alert message"
]
}
}
}
}
}
}
}
Example: Use the Default Template
This example uses the #default
template, which generates the appropriate payload for each type of device that receives it. The content is used to create a driver-specific payload for each supported notification provider. The parameters
object takes a required title
and optional body
, badge
, sound
, and custom
properties. Note that the sound
value names the WAV file. For APNS, this file must be in the app bundle. For WNS, the file must be in the app package (the service adds the mcs-appx:///
prefix automatically).
{
"template":{
"name":"#default",
"parameters":{
"title":"Sale On Now!",
"body":"50% off until Saturday",
"badge":5,
"sound":"alarm.wav",
"custom":{
"acme1":"value1",
"acme2":[
"value2",
"value3"
]
}
}
}
}
Here are examples of the driver-specific payloads that the server generates from this request body.
APNS Driver Payload:
{
"aps": {
"alert": {
"title": "Sale On Now!",
"body": "50% off until Saturday"
},
"badge": 43,
"sound": "alarm.wav",
},
"acme1": "value1",
"acme2": ["value2", "value3"]
}
FCM Driver Payload:
Custom properties are passed in a data
object in the generated payload and the other parameters are passed in a notification
object. This example of a generated payload contains both data
and notifications
objects for illustrative purposes. Typically, FMC notifications have either the notification
object or the data
object, but not both. Note that because FCM data are name/value pairs, the value for acme2
was converted from an array to a string.
{
"fcm":{
"notification":{
"title":"Sale On Now!",
"body":"50% off until Saturday",
"sound":"alarm.wav"
},
"data":{
"acme1":"value1",
"acme2":"[\"value2\", \"value3\"]"
}
}
}
WNS Driver Payload:
{
"toast": {
"visual": {
"binding": {
"template": "ToastText02",
"text": ["Sale on Now!", "50% off"]}},
"audio": {
"src": "ms-appx:///alarm.wav"},
"badge": {
"value": "43"},
"raw": {
"acme1": "value1",
"acme2": ["value2", "value3"]
}
}
For the WNS driver payload, three notifications are sent:
-
A toast notification for the alert and sound
-
A badge notification
-
A raw notification for the custom parameters
Example of Response Header
Here's an example of the response header:
201 CREATED
Content-Type: application/json; charset=UTF-8
Date: Tue, 23 Jun 2015 00:04:03 GMT
Location: /mobile/system/notifications/notifications/3
Example of Response Body
This example shows the contents of the response body in JSON format:
{
"id": 2,
"message": "Reminder: Status on incident 1548 is due",
"users": [
"technician14@fif.com",
"technician21@fif.com"
],
"roles": [ ],
"notificationTokens": [ ],
"sendOn": "2015-06-25T06:00Z",
"tag": "Incidents",
"status": "Scheduled",
"createdOn": "2015-06-22T23:48:20.738Z",
"links": [
{
"rel": "canonical",
"href": "/mobile/system/notifications/notifications/3"
},
{
"rel": "self",
"href": "/mobile/system/notifications/notifications/3"
}
]
}