Search
Link Search Menu Expand Document
Kony Quantum is now HCL Volt MX. See Revised Terminology. Current Quantum users, see the important note about API naming.
Release:

Push Message

The Push Message API sends push messages to the subscribed app users.

URL

The HTTP URL for Push Message API is:

http://<hostname/IP>:<port>/api/v1/messages/push

The API implements Gateway Filter for Authentication to authenticate access of the API by a user.

Method

POST

The payload’s request header includes Content-Type as application/json;charset=UTF-8 for JSON payload and text/xml;charset=UTF-8 for XML payload.

content-type: application/json;charset=UTF-8 OR text/xml;charset=UTF-8 (any one at a time)
Authorization : Required

Input Parameters

The following fields are input parameters:

Input Parameter Level – Two Level – Three Required Type Description
messageRequest         An array of messageRequest objects
  appId   Yes long Unique ID assigned to an app
  global   Optional   An array of global objects  
    subscribers     An array of subscribers
    subscriber: ksid OR ufid OR deviceId Optional string Array of subscribers’ ksid or ufid or deviceId
  messages       An array of messages objects
    message     An array of message objects
    message:expiryTimestamp Optional string Date on which the push message will expire
    message: overrideMessageId Optional long If you change the push message and yet the message is not sent, then you must pass the old message ID in a sample request to update the existing push message to be sent
    message: refId Optional alphanumeric The reference ID tracks failed push messages. refId is a unique identifier of the push message. Based on your requirement you can define a reference ID
    message: startTimestamp Optional date time format Time relative to a starting point
    message: expiryTimestamp Optional date time format Time relative to an ending point
    message: type Yes string Type of channel, such as push
    message: subscribers     An array of subscribers objects- segmentCriteria
    subscriber: ksid OR ufid OR deviceId Yes string Array of subscribers’ ksid or ufid or deviceId
  platformSpecificProps   Optional   An array of platform specific properties, For more details, see
  content       An array of content objects
    mimeType Optional string Label for data such as text/plain
    priorityService Optional boolean If it is priority service or not
    data Optional string push message description

Note: In a Global or Local array, you can pass a UFID or deviceId as an input parameter to send push content.
- UFID: The User Friendly Identifier, or UFID, is used when you subscribe to Volt MX Foundry Engagement Services. The UFID is an alphanumeric value. For example: xxx@VoltMX.com or 2890XZCY. It can be used to map devices to the user using the value as a reconciliation key. If you are sending a push message using UFID, then the push will send to all the devices that match the UFID.
- deviceId: A device identification, or deviceId, is a distinctive number associated with a device.

Important: When a standard push message is sent to Android devices, the app for which the push is sent is launched in the background (if it is not already running) before the standard push message is processed, This causes the creation of a session.
When a standard push message is sent to iOS devices, the push message is displayed by the platform and no session is created.

When a silent push message is sent to Android devices, the app for which the push is sent is launched in the background (if it is not already running) before the silent push is processed. This causes the creation of a session.
For the iOS devices, when a silent push is received and the app for which the message is sent is not running (because the app is killed by the user), then the message is not processed and no session is created.
For the iOS devices, when a silent push is received and the app for which the message is sent is not running (because the app is killed by the device due to a lack of resources or something similar), then the message is processed by launching the app in the background and a session is created.

Sample Request

XML 

  
 <?xml version="1.0" encoding="UTF-8"?>
<messageRequest>
<appId>15810-4190527911</appId>
<global>
<subscribers>
<subscriber>
<ksid>6338461620036073083</ksid> - OR -
<ufid>emailid@voltmx.com</ufid> - OR -
<deviceId>12345</deviceId>
</subscriber>
</subscribers>
</global>
<messages>
<message>
<content>
<data>You have received a message</data>
<mimeType>text/plain</mimeType>
<priorityService>true</priorityService>
</content>
<expiryTimestamp>0</expiryTimestamp>
<overrideMessageId>0</overrideMessageId>
<platformSpecificProps>
<android>
<bodyLocArgs>
<bodyLocArg>
<element>bodyArg1</element>
<element>bodyArg2</element>
<element>bodyArg3</element>
</bodyLocArg>
</bodyLocArgs>
<bodyLocKey>bodyLocKey</bodyLocKey>
<clickAction>Click action123</clickAction>
<color>red</color>
<delayWhileIdle>true</delayWhileIdle>
<icon>twitter.png</icon>
<key>
<name>xxxx</name>
<value>xxxx</value>
</key>
<priority>normal/high</priority>
<sound>bell.wav</sound>
<timeToLive>2490875</timeToLive>
<title>Android Tile</title>
<titleLocArgs>
<titleLocArg>
<element>titleArg1</element>
<element>titleArg2</element>
<element>titleArg3</element>
</titleLocArg>
</titleLocArgs>
<titleLocKey>titleLocKey</titleLocKey>
</android>
<blackberry>
<header>
<name>useEncoding</name>
<value>UTF-8</value>
</header>
</blackberry>
<iphone>
<actionLocKey>VIEW</actionLocKey>
<badge>1</badge>
<category>DOWNLOAD_CATEGORY</category>
<contentAvailable>1</contentAvailable>
<customData>
<key>
<content>userCustomData</content>
<name>userData</name>
</key>
</customData>
<launchImage>LaunchImage.png</launchImage>
<locArgs>
<locArg>
<element>Joe</element>
<element>Jane</element>
</locArg>
</locArgs>
<locKey>REPLYTO</locKey>
<sound>sample.wav</sound>
<title>Offer for you</title>
<titleLocArgs>
<titleLocArg>200</titleLocArg>
</titleLocArgs>
<titleLocKey>TITLE</titleLocKey>
</iphone>
<windows>
<badge>3</badge>
<imagePath>http://background.images.com/background</imagePath>
<notificationType>TILE</notificationType>
<title>New Message</title>
</windows>
<web>
<clickAction>Click action123</clickAction>
<icon>twitter.png</icon>
<key>
<name>xxxx</name>
<value>xxxx</value>
</key>
</web>
</platformSpecificProps>
<startTimestamp>0</startTimestamp>
<subscribers>
<segmentCriteria>##1## OR ##2##</segmentCriteria> - OR -
<subscriber>
<ksid>6338461620036073083</ksid> - OR -
<ufid>emailid@voltmx.com3</ksid> - OR -
<deviceId>12345</ksid>
</subscriber>
</subscribers>
<type>PUSH</type>
</message>
</messages>
</messageRequest>

JSON

Sample Request with Local Parameter 

  
 {
"messageRequest": {
"appId": "25016-9447884208",
"messages": {
"message": {
"expiryTimestamp": "0",
"overrideMessageId": "0",
"refId": "4567223425667",
"startTimestamp": "0",
"type": "PUSH",
"subscribers": {
   "segmentCriteria": "##4## OR ##3##" - OR -
"subscriber": {
"ksid": "6338461620036073083", - OR -
"ufid": "emailid@voltmx.com", - OR -
"deviceId": "12345"
},
},
"platformSpecificProps": {
"iphone": {
 "badge": "1",
   "sound": "sample.wav",
   "category": "DOWNLOAD_CATE",
    "contentAvailable": "1",
      "actionLocKey": "VIEW",
     "locKey": "REPLYTO",
"locArgs": {
    "locArg": [
"Joe",
"Jane"
]
},
"launchImage":"x.png",
"title": "Offer",
"titleLocKey": "TITLE",
"titleLocArgs": {
    "titleLocArg": "200"
},
"customData": {
"key": {
"name": "user",
"content": "userData"
}
}
},
"android": {
"title": "Android Tile",
"delayWhileIdle": true,
"priority": "normal/high",
"timeToLive": "2490875",
"sound": "bell.wav",
"icon": "twitter.png",
"color": "red",
"clickAction": "ac123",
"bodyLocKey": "bLKey",
"titleLocKey": "tLKey",
"titleLocArgs": {
"titleLocArg": [
"titleArg1", "titleArg2", "titleArg3"
]
},
"bodyLocArgs": {
"bodyLocArg": [
"bodyArg1", "bodyArg2", "bodyArg3"
]
},
"key": {
"name": "xxxx",
"value": "xxxx"
}
},
"blackberry": {
"header": {
"name": "useEncoding",
"value": "UTF-8"
}
},  
 "web": {
"title": "webTile",
"icon": "twitter.png",
"clickAction": "ac123",
"key": {
"name": "xxxx",
"value": "xxxx"
}
},
"windows": {
"notificationType": "TILE",
"title": "New Message",
"badge": "3",
"imagePath":  
"http://background.images.com/background"  
 }
},
"content": {
"mimeType": "text/plain",
"priorityService": "true",
"data": "You have a message"
}
}
}
}
}

Sample Request with Global Parameter 

  
 {
"messageRequest": {
"appId": "25016-9447884208",
"global": {
"subscribers": {
"subscriber": [{
"ksid": "9217145330768714746"
- OR -
"ufid": "emailid@voltmx.com"
- OR -
"deviceId": "12345"
}, {
"ksid": "9217178177779285998"
- OR -
"ufid": "emailid@voltmx.com"
- OR -
"deviceId": "12345"
}]
}
},
"messages": {
"message": {
"expiryTimestamp": "0",
"overrideMessageId": "0",
"refId": "45672234256622",
"startTimestamp": "0",
"type": "PUSH",
"subscribers": {
        "segmentCriteria": "##4## OR ##3##" - OR -
"subscriber": {
"ksid": "6338461620036073083" - OR -
"ufid": "emailid@voltmx.com" - OR -
"deviceId": "12345"
},
},
"platformSpecificProps": {
"iphone": {
         "badge": "1",
"sound": "sample.wav",
"category" "DOWNLOAD",
"contentAvailable": "1",
"actionLocKey": "VIEW",
"locKey": "REPLYTO",
"locArgs": {
"locArg": [
    "Joe",
    "Jane"
]
},
"launchImage": "x.png",
"title": "Offer for you",
"titleLocKey": "TITLE",
"titleLocArgs": {
"titleLocArg": "200"
},
"customData": {
"key": {
"name": "user",
"content": "userData"
}
}
},
"android": {
"title": "Android",
"delayWhileIdle": true,
"priority": "normal/high",
"timeToLive": "2490875",
"sound": "bell.wav",
"icon": "twitter.png",
"color": "red",
"clickAction": "ac123",
"bodyLocKey": "bLKey",
"titleLocKey": "tLKey",
"titleLocArgs": {
  "titleLocArg": [
"titleArg1",
 "titleArg2", "titleArg3"
]
},
"bodyLocArgs": {
  "bodyLocArg": [
"bodyArg1", "bodyArg2", "bodyArg3"
]
},
"key": {
 "name": "xxxx",
 "value": "xxxx"
}
},
"blackberry": {
"header": {
"name": "useEncoding",
"value": "UTF-8"
}
"web": {
"title": "webTile",
"icon": "twitter.png",
"clickAction": "ac123",
"key": {
"name": "xxxx",
"value": "xxxx"
}
},
},
"windows": {
   "notificationType": "TILE",
 "title": "New Message",
 "badge": "3",
 "imagePath":  
"http://background.images.com/background"
}
},
"content": {
"mimeType": "text/plain",
"priorityService": "true",
"data": "You have a message"
}
}
}
}
}

Output Parameters

The following fields are output parameters:

Output Parameter Level-Two Type Description
details     An array of details objects
  refId alphanumric Push message reference ID
  description string Displays the total number of pushes sent
  msgId long Here, msgId refers to an ID that is used to map messagerequest table and messageentry table for internal data record.
id     Here, id refers to request ID displayed under Settings > Status > List view > Request ID column
message   string Response status message

Sample Response 

{
"details" : [ {
"refId" : "",
"description" : "Number of Pushes queued:4",
"msgId" : "0"
} ],
"id" : "9221229698214870954",
"message" : "Request Queued. "
}

Note: If the push message request is valid, the supplied reference ID in the push message request is not reflected in the push message response. If the request is invalid, the reference ID is displayed with a valid response status.

Response Status

Code Description
Status 200 Request queued
Status 400 Invalid voltmx appId or application is not published with given appIdInvalid request format.
Status 401 Unauthorized request.
Status 500 Server failure to process request