Headers
Request Header | Description |
---|---|
key | Service Key |
content-type | application/json |
{
"correlationid": "<Unique transaction ID from the client end>",
"notifyurl": "<Notifications will be sent to the URL specified here>",
"callbackData": "<Identifier sent alongside notifications to the notifyurl>",
"expiry": "<Expiry time in UTC format, after which messages will not be pushed. For example, 2015-04-12T13:00:19.456Z or 2015-04-12T18:30:19.456+5:30.>",
"priority": "<Accepts numbers 1-low, 2-medium, and 3-high>",
"deliverychannel": "push",
"message": {
"template": "<Message template ID.>",
"parameters": {
"parameter1": "<value>",
"parameter2": "<value>",
"parameter3": "<value>"
}
},
"channels": {
"push": {
"ios": {
"text": "<iOS message>",
"extras": {Refer to iOS extras}
},
"android": {
"text": "<Android message>",
"priority": "<A value from 1 to 5, where 5 is the highest>",
"extras": {Refer to Android extras}
},
"web": {
"title": "<title text for web browser push message>",
"text": "<push message text for Web browser>",
"url": "<URL that opens when message is clicked>",
"actiontext": "<Specifies the text of the button for safari browsers only>",
"platorm_types": ["chrome", "safari", "firefox"],
"extras": {Refer to web extras}
},
"interactive": {
"pushref": "<Provide a reference value if the results of the push interaction is required as a trigger for rules.>",
"device_types": [
"ios",
"android"
],
"category": "<Each category has a specific context and associated set of actions. Refer to the list of categories.>",
"actions": [{
"pos": 1,
"action": "<Actions depend on the category>",
"value": "<Value depends on the action>"
}, {
"pos": 2,
"action": "<Actions depend on the category>",
"value": "<Value depends on the action>"
}]
}
}
},
"destination": [{
"customerid/android_pushid/ios_pushid/chrome_pushid/firefox_pushid/safari_pushid": [
"<value1>",
"<value2>"
],
"correlationid": "<A unique transaction ID up to 50 bytes used by Client to match requests with responses. Will override correlationid given in request body.>", "deviceId":"4d0667b4853cd333"
}, {
"customerid/android_pushid/ios_pushid/chrome_pushid/firefox_pushid/safari_pushid": [
"<value1>",
"<value2>"
],
"correlationid": "<A unique transaction ID up to 50 bytes used by Client to match requests with responses. Will override correlationid given in request body.>"
}]
}
Body Parameters
The section below details all the parameters of the request body:
Parameter | Type | Mandatory | Description |
---|---|---|---|
deliverychannel | String | Yes | Specifies the channel to send a message. |
destination | JSONArray | Yes | The destination parameter is an array of up to 1,000 entries. Messages can be sent to single or multiple recipients in a single request. For more details, refer to destination array. |
channels | JSONArray | Yes | The channel parameter encompasses sub-parameters. |
message | JSONObject | No | The message parameter block references a template via the template ID which is created within the IMIconnect platform. The amount of sub-parameters in the parameters block depends on the number of parameters expected in the template. These parameters are supplied to the template for substitution in the final message.
Note: If you use message templates, then the parameter name should match with the parameter specified in the template. The parameters in this message block are overridden if a channel specific parameter block is also used.
|
expiry | String | No | Expiry time in UTC format, after which messages will not be pushed. For example, 2015-04-12T13:00:19.456Z or 2015-04-12T18:30:19.456+5:30. |
correlationid | String | No | A unique transaction ID up to 50 bytes used by Service Providers to match requests with responses. |
notifyurl | String | No | The IMIconnect platform will send notifications to the URL specified in the notifyurl parameter. The URL is used to retrieve the status of the message sent. The notifyurl can also be configured while creating a service. If the URL is specified in both the service and the messaging API, preference will be given to the messaging API request. For more information on notify URL formats, click Message Receipts. |
callbackData | String | No | Data to be passed alongside notifications to the notifyurl. This can serve as identifying notifications. |
priority | String | No | This parameter is used to specify the message priority. The priority is defined while creating the client in the admin screen. All the services that are created under this client will have same priority. Messages of equal priorities are delivered in the natural order of their arrival at their destinations. The options for this parameter are:
If any invalid option or text is passed, then the priority is set as configured while creating the client. |
channels
The channels parameter block configures channel communication parameters and will overrides the service's default values and the parameters in the base request.
Push Notifications
Parameter | Type | Mandatory | Description |
---|---|---|---|
android | JSONObject | No | This is a parameter block with Android specific Push settings. |
ios | JSONObject | No | This is a parameter block with iOS specific Push settings. |
interactive | JSONObject | No | This is a parameter block with the following:
|
web | JSONObject | No | This is a parameter block with web browser specific Push settings.
|
{
"channels": {
"push": {
"pushref": "<Provide a reference value if the results of the push interaction is required as a trigger for rules.>",
"ios": {
"text": "<iOS specific push message text>",
"extras": {Refer to iOS extras}
},
"android": {
"text": "<Android specific message text>",
"priority": "<A value from 1 to 5, where 5 is the highest>",
"extras": {Refer to Android extras}
},
"web": {
"title": "<title text for web browser push message>",
"text": "<push message text for Web browser>",
"url": "<URL that opens when message is clicked>",
"actiontext": "<Specifies the text for button for safari browsers only>",
"platorm_types": "<specifies the browser to which the message is sent>",
"extras": {Refer to web extras}
},
"interactive": {
"device_types": [
"ios",
"android"
],
"category": "<Each category has a specific context and associated set of actions. Refer to the list of categories.>",
"actions": [{
"pos": 1,
"action": "<Actions depend on the category>",
"value": "<Value depends on the action>"
}, {
"pos": 2,
"action": "<Actions depend on the category>",
"value": "<Value depends on the action>"
}]
}
}
}
}
Either android or ios or web parameter must be passed.
Android
The following parameters are part of the android parameter block which in turn is part of the push block.
Parameter | Type | Mandatory | Description |
---|---|---|---|
text | String | Yes | Android specific text message . |
extras | JSONObject | No | A parameter block consisting of:
|
priority | Integer | No | A value from 1 to 5, where 5 is the highest. The default value is 3. |
title | String | No | Message title. |
{
"channels":{
"push":{
"android":{
"text":"<Android message>",
"title": "android message title",
"extras":{Refer to Android extras}
}
}
}
- push > android > Android extras
The following parameters are part of the extras parameter block which in turn is part of the android block.
Parameter | Type | Mandatory | Description |
---|---|---|---|
collapse_key | String | No | An arbitrary string that is used to replace the older message with new message when the older message did not reached the destination. |
time_to_live | String | No | Expiry time for the message in seconds. |
sound | String | No | Default / Custom sound will be played when the notification delivered. The options are:
|
delay_while_idle | String | No | If true, the message delivery is delayed when the customer’s device is idle. Options are:
|
customtags | JSONObject | No | A user defined key-value pair. The value can be a string or JSON object, or a JSON array. This object contains a reserved parameter: |
notificationaction | JSONObject | No | Define this object to add an action when the notification is clicked. The sub parameters of this block are:
|
iconurl | String | No | Corresponds to Android Push notification image received on the mobile. |
notificationChannelId | String | No | Starting on Android 8.0, all notifications must be assigned to a Notification channel or it will not appear.Instead of disabling all the notifications, user can control notification by disabling a specific channel on the app. |
{
"collapse_key":"<Alpha numeric key>",
"sound":"<default/custom sound>",
"time_to_live":"<integer value>",
"delay_while_idle":"[true|false]",
"customtags":{"key1":"object1","key2":{"object2":"val"},"key3":["object3","object4"]},
"notificationaction": {
"action": "OPEN_URL",
"value": "www.google.com"
}
}
The following parameters are part of the notificationaction parameter block which in turn is part of the extras block.
Parameter | Type | Mandatory | Description |
---|---|---|---|
action | String | No | You can configure the following for an action:
|
value | String | No | Specifies the value that is used to complete the action configured. For example, if you configure action as OPEN_URL, then you have to configure value with a URL such as www.bbc.com.**Note: If the action is set to OPENAPP**, value is not required. |
It is not mandatory to define notificationaction. But if you set an action, you must specify a _value _that is used to complete the configured action.
iOS
The following parameters are part of the ios parameter block which in turn is part of the channels block.
Parameter | Type | Mandatory | Description |
---|---|---|---|
text | String | Yes | iOS specific text message. |
extras | JSONObject | No | A parameter block consisting of:
|
{
"channels":{
"push":{
"ios":{
"text":"<iOS message>",
"title": "ios message title",
"extras":{Refer to ios extras}
}
}
}
- push > ios > ios extras
The following parameters are part of the ios parameter block which in turn is part of the push block.
Parameter | Type | Mandatory | Description |
---|---|---|---|
badge | String | No | The number to be displayed as badge of the app icon. |
sound | String | No | Default / Custom sound that should be played when the notification is delivered. The options are:
|
time_to_live | String | No | Expiry time for the message in seconds. |
silentpush | String | No | The customer will not get the notification of the delivered message, but the app receives the pushed message if this attribute is true. The options are:
|
customtags | JSONObject | No | A user defined key-value pair. The value can be a string or JSON object, or a JSON array. |
notificationaction | JSONObject | No | Define this object to add an action when the notification is clicked. The sub parameters of this block are:
|
{
"badge": "<badge number>",
"sound": "<default/custom sound>",
"time_to_live": "<integer value>",
"silentpush": "[true|false]",
"customtags": {
"key1": "object1",
"key2": {
"object2": "val"
},
"key3": ["object3", "object4"]
},
"notificationaction": {
"action": "OPEN_URL",
"value": "www.google.com"
}
}
The following parameters are part of the notificationaction parameter block which in turn is part of the extras block.
Parameter | Type | Mandatory | Description |
---|---|---|---|
action | String | No | You can configure the following for an action:
|
value | String | No | Specifies the value that is used to complete the action configured. For example, if you configure action as OPEN_URL, then you have to configure value with a URL such as www.bbc.com.**Note: If the action is set to OPENAPP**, value is not required. |
It is not mandatory to define notificationaction. But if you set an action, you must specify a _value _that is used to complete the configured action.
web
The following parameters are part of the web parameter block which in turn is part of the push block.
Parameter | Type | Mandatory | Description |
---|---|---|---|
title | String | Yes | Specifies the title of the web browser push message. |
text | String | Yes | Specifies the push message for web browser. |
url | String | No | Specifies the URL that opens when the message is clicked. |
actiontext | String | Yes | Specifies the text of the button. This parameter is applicable to Safari browser only. |
platform_types | JSONArray | Yes | Specifies the browsers to which the message is sent. |
extras | JSONObject | No | A parameter block consisting of:
Note: The parameter collapse_key is not applicable to safari browser. |
{
"deliverychannel": "push",
"channels": {
"push": {
"web": {
"platform_types": ["firefox", "chrome", "safari"],
"title": "Offers",
"text": "50% off on google apps",
"actiontext": "view",
"url": "https://play.google.com/myaps/50"
}
}
},
"destination": [{
"customerid": [
"304"
]
}]
}
// Web browser notification
{
"web": {
"title": "<title text for web browser push message>",
"text": "<push message text for Web browser>",
"url": "<URL that opens when message is clicked>",
"actiontext": "<Specifies the text of the button for safari browsers only>",
"platorm_types": ["chrome", "safari", "firefox"], //Specifies the browsers to which the message is sent.
"extras": {
"collapse_key": "<Alpha numeric key>", //If two messages have same collapse key, older message is discarded on the end device.
"time_to_live": "<integer value>", //Number of seconds that a message may be stored if the user is not immediately available. Max of 51840000.
"customtags": {
"key1": "object1",
"key2": {
"object2": "val"
},
"key3": ["object3", "object4"]
}
}
}
}
push > web > extras
The following parameters are part of the web parameter block which in turn is part of the push block.
Parameter | Type | Mandatory | Description |
---|---|---|---|
collapse_key | String | No | An arbitrary string that is used to replace the older message with new message when the older message did not reached the destination.Note:The parameter collapse_key is not applicable to safari browser. |
time_to_live | String | No | Expiry time for the message in seconds. |
customtags | JSONObject | No | A user defined key-value pair. The value can be a string or JSON object, or a JSON array. |
push > interactive
The following parameters are part of the interactive parameter block which in turn is part of the push block.
Parameter | Type | Mandatory | Description |
---|---|---|---|
device_types | JSONArray | Yes, atleast one | The device types that should receive the interactive notifications.
|
pushref | String | No | This is an optional parameter to be defined in the push JSON if the sender intends to use the push interaction result as a trigger for rules. |
category | String | Yes | Either one the below categories should be passed
|
actions | JSONArray | Yes | The JSON array should contain the following.
pos
|
smartlinks
An array that contains the parameters of Smartlink. This is an optional parameter. To use Smartlinks, you must create a smartlink and use the link id in messaging API. These Smartlinks can be used in SMS, RT and OTT messaging channels.
Following are the parameters of smartlinks:
Parameter | Type | Mandatory | Description |
---|---|---|---|
linkid | Number | Yes | This parameter is mandatory when the smartlinks parameter is configured. The linkid gets generated for a smartlink created using IMIconnect. |
validity | Number | No | Specifies the time in minutes after which the link will expire. |
{
"smartlinks":[
{
"linkid": "<specifies the link id that is generated for a Smartlink using IMIconnect. >",
"validity": "<Specifies the time in minutes after which the link will expire>"
}
]
}
Response Body
{
"response": [
{
"code": "1001",
"description": "Queued",
"transid": "f9793c83-f0b7-4200-99d9-20111c507baf",
"correlationid": "cid"
}
]
}