1. REST API Reference for Oracle Mobile Hub - Platform APIs
  2. Tasks
  3. Notifications

Create Notification

post

/mobile/system/notifications/notifications/

Call this operation to create a new 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 team member with either the Administrator or Developer role.

Request

Supported Media Types
Body ()
Root Schema : User-entered notification
Type: object
Title: User-entered notification
Match All
Show Source
  • Notification properties
    Title: Notification properties
  • 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). The maximum payload size dependes on the provider. For APNS and FCM, the payload size limit is 4096 bytes, for WNS the limit is 5000 bytes, and for Syniverse the limit is 1000 bytes.
Nested Schema : Notification properties
Type: object
Title: Notification properties
Show Source
  • notificationTokens
    Minimum Number of Items: 1
    Maximum Number of Items: 1000
    Unique Items Required: true
    Select devices to send the notification to by `notificationToken`.
  • Title: Supported platforms
    Allowed Values: [ "IOS", "ANDROID", "WINDOWS", "WEB" ]
  • Title: Supported notification providers. Support for GCM is deprecated. You should upgrade all GCM applications to FCM.
    Allowed Values: [ "APNS", "GCM", "FCM", "WNS", "SYNIVERSE" ]
  • 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).
  • User-defined tag that you use to categorize notifications.
  • users
    Minimum Number of Items: 1
    Unique Items Required: true
    Select devices to send the notification to by `user`.
Nested Schema : Notification payload
Type: object
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). The maximum payload size dependes on the provider. For APNS and FCM, the payload size limit is 4096 bytes, for WNS the limit is 5000 bytes, and for Syniverse the limit is 1000 bytes.
Show Source
Nested Schema : notificationTokens
Type: array
Minimum Number of Items: 1
Maximum Number of Items: 1000
Unique Items Required: true
Select devices to send the notification to by `notificationToken`.
Show Source
Nested Schema : users
Type: array
Minimum Number of Items: 1
Unique Items Required: true
Select devices to send the notification to by `user`.
Show Source
Nested Schema : Unified payload for notification providers
Type: object
Title: Unified payload for notification providers
Show Source
Nested Schema : Template reference
Type: object
Title: Template reference
Name and parameters for a template from which to create the payload
Show Source
Nested Schema : Notification payloads for specific providers
Type: object
Title: Notification payloads for specific providers
Show Source
Nested Schema : apns
Type: object
If specified, this payload is used for notifications sent using APNS. This object must conform to APNS requirements.
Nested Schema : fcm
Type: object
If specified, this payload is used for notifications sent using FCM. An 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.
Nested Schema : gcm
Type: object
Deprecated. You should upgrade all GCM applications to FCM.
Nested Schema : Syniverse payload
Type: object
Title: Syniverse payload
Show Source
Nested Schema : WNS payload
Type: object
Title: WNS payload
Show Source
Nested Schema : Badge value or glyph
Type: object
Title: Badge value or glyph
Show Source
  • Either a numeric value or a string value that specifies a predefined badge glyph.
  • The version of the badge XML schema that this particular payload was developed for.
Nested Schema : Raw payload
Type: object
Title: Raw payload
Specifies a raw payload. This is any arbitrary JSON object.
Nested Schema : Base tile element
Type: object
Title: Base tile element
Base tile element, which contains a single visual element.
Show Source
Nested Schema : Base toast element
Type: object
Title: Base toast element
Base toast element, which contains at least a single visual element.
Show Source
Nested Schema : Binding child elements
Type: object
Title: Binding child elements
Match All
Show Source
Nested Schema : Child element properties
Type: object
Title: Child element properties
Show Source
Nested Schema : Common visual and binding properties
Type: object
Title: Common visual and binding properties
Show Source
Nested Schema : binding
Type: array
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.
Show Source
Nested Schema : Toast template
Type: object
Title: Toast template
Match All
Show Source
Nested Schema : Toast template properties
Type: object
Title: Toast template properties
Show Source
Nested Schema : image
Type: array
Minimum Number of Items: 0
Specifies an image to use in the toast template.
Show Source
Nested Schema : text
Type: array
Minimum Number of Items: 1
Specifies text to use in the toast template.
Show Source
Nested Schema : Image to use in a toast or tile template
Type: object
Title: Image to use in a toast or tile template
Show Source
Nested Schema : Sound to play
Type: object
Title: Sound to play
Specifies a sound to play when a toast is displayed. This element also allows you to mute toast audio.
Show Source
Nested Schema : Scenario commands
Type: object
Title: Scenario commands
Specifies that the toast indicates an incoming call or an alarm, with appropriate commands associated with each scenario.
Show Source
Nested Schema : Single binding element that defines a toast
Type: object
Title: Single binding element that defines a toast
Match All
Show Source
Nested Schema : commands
Type: array
Minimum Number of Items: 1
Specifies the scenario-associated buttons shown in the toast.
Show Source
  • Scenario button
    Title: Scenario button
    Specifies a scenario-associated button shown in a toast. The scenario is specified in the parent commands element.
Nested Schema : Scenario button
Type: object
Title: Scenario button
Specifies a scenario-associated button shown in a toast. The scenario is specified in the parent commands element.
Show Source
  • 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.
  • Specifies one command from the system-defined command list.
Nested Schema : Element properties
Type: object
Title: Element properties
Show Source
Nested Schema : parameters
Type: object
The template parameters. The required parameters are defined by the template.
Example Request (application/json)
{
    "notificationTokens":[
        "APNSdeviceToken"
    ],
    "tag":"Marketing",
    "message":"This is the alert message."
}
Back to Top

Response

Supported Media Types

201 Response

The notification was created and the notification object was returned.
Headers
Body ()
Root Schema : Stored notification
Type: object
Title: Stored notification
Match All
Show Source
Nested Schema : Stored notification properties
Type: object
Title: Stored notification properties
Show Source
  • 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).
  • 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`.
  • Message explaining a status of `Error` or `Warning`. If there are multiple associated problems, only the first is shown here.
  • Service-generated identifier.
  • Relationship links
  • platformCounts
    Minimum Number of Items: 1
    Unique Items Required: true
    Device counts by platform.
  • 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).
  • Title: Status values
    Allowed Values: [ "New", "Scheduled", "Sending", "Error", "Warning", "Sent" ]
Nested Schema : User-entered notification
Type: object
Title: User-entered notification
Match All
Show Source
  • Notification properties
    Title: Notification properties
  • 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). The maximum payload size dependes on the provider. For APNS and FCM, the payload size limit is 4096 bytes, for WNS the limit is 5000 bytes, and for Syniverse the limit is 1000 bytes.
Nested Schema : platformCounts
Type: array
Minimum Number of Items: 1
Unique Items Required: true
Device counts by platform.
Show Source
Nested Schema : Device counts for a platform
Type: object
Title: Device counts for a platform
Show Source
Nested Schema : Notification properties
Type: object
Title: Notification properties
Show Source
  • notificationTokens
    Minimum Number of Items: 1
    Maximum Number of Items: 1000
    Unique Items Required: true
    Select devices to send the notification to by `notificationToken`.
  • Title: Supported platforms
    Allowed Values: [ "IOS", "ANDROID", "WINDOWS", "WEB" ]
  • Title: Supported notification providers. Support for GCM is deprecated. You should upgrade all GCM applications to FCM.
    Allowed Values: [ "APNS", "GCM", "FCM", "WNS", "SYNIVERSE" ]
  • 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).
  • User-defined tag that you use to categorize notifications.
  • users
    Minimum Number of Items: 1
    Unique Items Required: true
    Select devices to send the notification to by `user`.
Nested Schema : Notification payload
Type: object
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). The maximum payload size dependes on the provider. For APNS and FCM, the payload size limit is 4096 bytes, for WNS the limit is 5000 bytes, and for Syniverse the limit is 1000 bytes.
Show Source
Nested Schema : notificationTokens
Type: array
Minimum Number of Items: 1
Maximum Number of Items: 1000
Unique Items Required: true
Select devices to send the notification to by `notificationToken`.
Show Source
Nested Schema : users
Type: array
Minimum Number of Items: 1
Unique Items Required: true
Select devices to send the notification to by `user`.
Show Source
Nested Schema : Unified payload for notification providers
Type: object
Title: Unified payload for notification providers
Show Source
Nested Schema : Template reference
Type: object
Title: Template reference
Name and parameters for a template from which to create the payload
Show Source
Nested Schema : Notification payloads for specific providers
Type: object
Title: Notification payloads for specific providers
Show Source
Nested Schema : apns
Type: object
If specified, this payload is used for notifications sent using APNS. This object must conform to APNS requirements.
Nested Schema : fcm
Type: object
If specified, this payload is used for notifications sent using FCM. An 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.
Nested Schema : gcm
Type: object
Deprecated. You should upgrade all GCM applications to FCM.
Nested Schema : Syniverse payload
Type: object
Title: Syniverse payload
Show Source
Nested Schema : WNS payload
Type: object
Title: WNS payload
Show Source
Nested Schema : Badge value or glyph
Type: object
Title: Badge value or glyph
Show Source
  • Either a numeric value or a string value that specifies a predefined badge glyph.
  • The version of the badge XML schema that this particular payload was developed for.
Nested Schema : Raw payload
Type: object
Title: Raw payload
Specifies a raw payload. This is any arbitrary JSON object.
Nested Schema : Base tile element
Type: object
Title: Base tile element
Base tile element, which contains a single visual element.
Show Source
Nested Schema : Base toast element
Type: object
Title: Base toast element
Base toast element, which contains at least a single visual element.
Show Source
Nested Schema : Binding child elements
Type: object
Title: Binding child elements
Match All
Show Source
Nested Schema : Child element properties
Type: object
Title: Child element properties
Show Source
Nested Schema : Common visual and binding properties
Type: object
Title: Common visual and binding properties
Show Source
Nested Schema : binding
Type: array
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.
Show Source
Nested Schema : Toast template
Type: object
Title: Toast template
Match All
Show Source
Nested Schema : Toast template properties
Type: object
Title: Toast template properties
Show Source
Nested Schema : image
Type: array
Minimum Number of Items: 0
Specifies an image to use in the toast template.
Show Source
Nested Schema : text
Type: array
Minimum Number of Items: 1
Specifies text to use in the toast template.
Show Source
Nested Schema : Image to use in a toast or tile template
Type: object
Title: Image to use in a toast or tile template
Show Source
Nested Schema : Sound to play
Type: object
Title: Sound to play
Specifies a sound to play when a toast is displayed. This element also allows you to mute toast audio.
Show Source
Nested Schema : Scenario commands
Type: object
Title: Scenario commands
Specifies that the toast indicates an incoming call or an alarm, with appropriate commands associated with each scenario.
Show Source
Nested Schema : Single binding element that defines a toast
Type: object
Title: Single binding element that defines a toast
Match All
Show Source
Nested Schema : commands
Type: array
Minimum Number of Items: 1
Specifies the scenario-associated buttons shown in the toast.
Show Source
  • Scenario button
    Title: Scenario button
    Specifies a scenario-associated button shown in a toast. The scenario is specified in the parent commands element.
Nested Schema : Scenario button
Type: object
Title: Scenario button
Specifies a scenario-associated button shown in a toast. The scenario is specified in the parent commands element.
Show Source
  • 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.
  • Specifies one command from the system-defined command list.
Nested Schema : Element properties
Type: object
Title: Element properties
Show Source
Nested Schema : parameters
Type: object
The template parameters. The required parameters are defined by the template.
Example Response (application/json)
{
    "notificationTokens":[
        "APNSdeviceToken"
    ],
    "links":[
        {
            "rel":"canonical",
            "href":"/mobile/system/notifications/notifications/1234"
        },
        {
            "rel":"self",
            "href":"/mobile/system/notifications/notifications/1234"
        }
    ],
    "id":1234,
    "tag":"Marketing",
    "message":"This is the alert message",
    "createdOn":"2014-04-02T12:34:56.789Z",
    "status":"New"
}

400 Response

The notification is missing or invalid.
Body ()
Root Schema : Error
Type: object
Title: Error
The error JSON object returned by the service.
Show Source
Nested Schema : o:errorDetails
Type: array
Minimum Number of Items: 0
Included when the error is caused by multiple issues.
Show Source
Nested Schema : Error Detail
Type: object
Title: Error Detail
Show Source
Back to Top

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 a notification object or a data 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"
    }
  ]
}
Back to Top