For up-to-date product documentation, see the IBM MobileFirst Foundation Developer Center.

Bulk Push Messages (POST)

Send bulk messages with different options that we can specify.

Method

POST

Path

/apps/applicationId/messages/bulk

Example

https://example.com:443/imfpush/v1/apps/myapp/messages/bulk

Path Parameters

applicationId

The name or identifier of the application

Header Parameters

Some header parameters are optional.

Authorization

The token with the scope "messages.write" and "push.application.<applicationId>" obtained using the confidential client in the format Bearer token.. This parameter has to be mandatorily set.

Consumes

application/json

Produces

application/json

Payload

The payload in JSON format has values for array of messages, target, and settings.

JSON Example

{
  "//ArrayOfMessageBody" : [
    {
      "messages" : {
        "alert" : "Test message",
      },
      "notificationType" : 1,
      "settings" : {
        "apns" : {
          "badge" : 1,
          "iosActionKey" : "Ok",
          "payload" : {"custom":"data"},
          "sound" : "song.mp3",
          "type" : "SILENT",
        },
        "gcm" : {
          "delayWhileIdle" : false,
          "payload" : {"custom":"data"},
          "sound" : "song.mp3",
          "timeToLive" : 10,
        },
        "wns" : {
          "badge" : {"value":"10"},
          "cachePolicy" : false,
          "expirationTime" : 20,
          "raw" : {"payload":{"custom":"data"}},
          "tile" : {"visual":{"binding":[{"template":"TileSquareText04", "text": [{"content":"Text1"}]}, {"template":"TileWideText04","text": [{"content":"Text1"}]}]}},
          "toast" : {"launch":{"custom":"data"}, "visual":{"binding":{"template":"ToastText04","text":[{"content":"Text1"},{"content":"Text2"},{"content":"Text3"}]}},
        },
      },
      "target" : {
        "deviceIds" : [ "MyDeviceId1", ... ],
        "platforms" : [ "A,G", ... ],
        "tagNames" : [ "Gold", ... ],
        "userIds" : [ "MyUserId", ... ],
      },
    },
    ...
  ],
}

Payload Properties

The payload has the following properties:

//ArrayOfMessageBody

The array of message

The bulk-messages has the following properties:

messages

The array of message

notificationType

Integer value to indicate the channel (Push/SMS) used to send message. Allowed values are 1 (only Push), 2 (only SMS) and 3 (Push and SMS)

settings

The settings are the different attributes of the notification.

target

Set of targets can be userIds, devices, platforms, or tags.

The message has the following properties:

alert

A string to be displayed in the alert.

The settings has the following properties:

apns

Attributes for sending message to an iOS device.

gcm

Attributes for sending message to an Android device.

wns

Attributes for sending message to a windows device.

The apns has the following properties:

badge

An integer value to be displayed in a badge on the application icon.

iosActionKey

The label of the dialog box button that allows the user to open the app upon receiving the notification.

payload

A JSON block that is transferred to the application if the application is opened by the user when the notification is received, or if the application is already open.

sound

The name of a file to play when the notification arrives.

type

Specify the type of APNS notification. It should be either DEFAULT, MIXED or SILENT

The gcm has the following properties:

delayWhileIdle

A Boolean value that indicates that the message must not be sent if the device is idle. The server waits for the device to become active before the message is sent.

payload

A JSON block that is transferred to the application if the application is opened by the user when the notification is received, or if the application is already open.

sound

The name of a sound file on the device to play when the notification arrives to the device.

timeToLive

The duration (in seconds) that the message is kept on GCM storage if the device is offline. Default value is 4 weeks, and must be set as a JSON number.

The wns has the following properties:

badge

cachePolicy

A boolean value that indicates if the notification should be cached or not.

expirationTime

Optional. Expriry time of the notification.

raw

tile

toast

The badge has the following properties:

value

Optional. A numeric or string value that indicates a prdefined glyph to be displayed.

version

Optional. Version of the payload.

The raw has the following properties:

payload

Optional. A JSON block that is transferred to the application only if the application is already open.

The tile has the following properties:

tag

Optional. A string value that is set as label for the notification. Used in notification cycling.

visual

The visual has the following properties:

addImageQuery

Optional. A boolean value that indicates if the query string need to be appended to image URI.

baseUri

Optional. Base URI to be combined with the relative URIs.

binding

For tile notifications, its a JSON array containing JSON blocks of binding attributes. For toast notification, its a JSON block of binding attributes.

branding

Optional. Indicates whether logo or app's name to be shown. Default is None.

contentId

Optional. A string value that identifies the notification content. Only applies to tile notifications.

lang

Optional. Locale of the payload.

version

Optional. Version of the payload.

The binding has the following properties:

addImageQuery

Optional. A boolean value that indicates if the query string need to be appended to image URI.

baseUri

Optional. Base URI to be combined with the relative URIs.

branding

Optional. Indicates whether logo or app's name to be shown. Default is None.

contentId

Optional. A string value that identifies the notification content. Only applies to tile notifications.

fallback

Optional. Template to be used as a fallback.

image

Optional. A JSON array containing JSON blocks of following image attributes.

lang

Optional. Locale of the payload.

template

Mandatory. Template type of the notification.

text

Optional. A JSON array containing JSON blocks of following text attributes.

The image has the following properties:

addImageQuery

Optional. A boolean value that indicates if the query string need to be appended to image URI.

alt

Optional. Image description.

src

Mandatory. Image URI.

The text has the following properties:

content

Mandatory. A string value that is displayed in the toast.

lang

Optional. Locale of the payload.

The toast has the following properties:

audio

duration

Optional. Notification will be displayed for the specified duration. Should be 'short' or 'long'.

launch

Optional. A string value that is passed to the application when it is launched by tapping or clicking the toast notification.

visual

The audio has the following properties:

loop

Optional. A boolean value to indicate if the sound should be repeated or not.

silent

Optional. A boolean value to indicate if the sound should be played or not.

src

Optional. A string value that specifies the notification sound type or path to local audio file.

The target has the following properties:

deviceIds

An array of the devices represented by the device identifiers. Devices with these ids receive the notification. This is a unicast notification

platforms

An array of device platforms. Devices running on these platforms receive the notification. Supported values are A (Apple/iOS), G (Google/Android) and W (Microsoft/Windows).

tagNames

An array of tags specified as tagNames. Devices that are subscribed to these tags receive the notification. Use this type of target for tag based notifications

userIds

An array of users represented by their userIds to send the notification. This is a unicast notification.

Errors

400

Bad Request - The request was not understood by the push server. An invalid JSON could result in this error code.

401

Unauthorized - The caller is either not authenticated or not authorized to make this request.

404

The application does not exist.

500

An internal error occurred.

Parent topic: REST API for the MobileFirst Server push service