Headers

Request HeaderDescription
keyService Key
content-typeapplication/json
##Request Body
{
    "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.

   "message":{        "template":"<Template ID>",      "parameters":{           "parameter1":"<value>",         "parameter2":"<value>",         "parameter3":"<value>"      },   }

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.
The message length is limited as per channel used. The sizes are:

  • SMS: 1024 bytes
  • Application notifications:
  • Android: 4096 bytes
  • iOS: 4096 bytes

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:

  • 1 - low
  • 2 - Medium
  • 3 - High

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:

  • pushref

  • device_types

  • ios

  • android

  • windows

  • category

  • actions (array block)

    • pos

    • action

    • value

web

JSONObject

No

This is a parameter block with web browser specific Push settings.

  • title

  • text

  • url

  • actionText

  • platform_types

  • extras

    • time_to_live

    • collapse_key

    • customtags

{
    "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:

  • collapse_key

  • time_to_live

  • sound

  • delay_while_idle

  • customtags

  • notificationaction

priorityIntegerNoA value from 1 to 5, where 5 is the highest. The default value is 3.
titleStringNoMessage 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:

  • default

  • custom sound

delay_while_idle

String

No

If true, the message delivery is delayed when the customer’s device is idle.

Options are:

  • true

  • false

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:
imageurl: It accepts a URL as string. This parameter is used to send images in notification.

notificationaction

JSONObject

No

Define this object to add an action when the notification is clicked. The sub parameters of this block are:

  • action

  • value

iconurlStringNoCorresponds to Android Push notification image received on the mobile.
notificationChannelIdStringNoStarting 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:

  • OPEN_URL: Requires a URL as action value.

  • OPEN_WEBVIEW: Requires a URL as action value.

  • OPEN_HTML: Requires a html code to render as action value.

  • DEEPLINK: Requires a deeplink URL as action value.

  • OPEN_APP: Does not require an action value.

valueStringNoSpecifies 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:

  • badge

  • sound

  • time_to_live

  • silentpush

  • url

  • html

  • customtags

  • notificationaction

  • collapse_key

  • attachmenturl

{
  "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:

  • default

  • custom sound

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:

  • true

  • false

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:

  • action

  • value

{
    "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:

  • OPEN_URL: Requires a URL as action value.

  • OPEN_WEBVIEW: Requires a URL as action value.

  • OPEN_HTML: Requires a html code to render as action value.

  • DEEPLINK: Requires a deeplink URL as action value.

  • OPEN_APP: Does not require an action value.

valueStringNoSpecifies 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:

  • time_to_live

  • collapse_key

  • customtags

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.

ParameterTypeMandatoryDescription
collapse_keyStringNoAn 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_liveStringNoExpiry time for the message in seconds.
customtagsJSONObjectNoA 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.

  • android

  • ios

  • windows

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

  • SINGLE_DISMISS
  • SINGLE_OPEN
  • SINGLE_SUBSCRIBE
  • SINGLE_UNSUBSCRIBE
  • SINGLE_SHARE
  • SINGLE_DEEPLINK
  • SINGLE_REPLY
  • DOUBLE_YES_NO
  • DOUBLE_ACCEPT_CANCEL
  • DOUBLE_SHARE_CANCEL
  • DOUBLE_SHOPNOW_CANCEL
  • DOUBLE_LATER_NOW

  • DOUBLE_PLAY_NOW_PLAY_LATER

  • DOUBLE_OK_LEARN_MORE

  • DOUBLE_SUBSCRIBE_UNSUBSCRIBE

  • DOUBLE_BUY_NOW_BUY_LATER

  • DOUBLE_LIKE_SHARE

actions

JSONArray

Yes

The JSON array should contain the following.

{    "pos": 1,   "action": "<Actions depend on the category>",    "identifier":<Identifier depends on the action.>    "value": "<Value depends on the action>" }

pos
Specifies the position of the button. Either 1 or 2.
action
Action for the notification buttons. Available actions are

  • DISMISS
  • OPEN_URL (Requires URL to be opened in value parameter)
  • OPEN_APP
  • DEEPLINK (Requires app page to be opened in value parameter)
  • OPENWEBVIEW (Requires URL to be opened in value parameter)
  • SHARE (Requires the content to be shared)

    identifier
    Identifier depends on the action. For example, if the action is DOUBLE_SHOPNOW_CANCEL, then identifier 1 will be SHOPNOW identifier 2 will be CANCEL. Refer to Push notification section for detail list of all identifiers
    value
    Specifies the value for the action.

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:

ParameterTypeMandatoryDescription
linkidNumberYesThis parameter is mandatory when the smartlinks parameter is configured. The linkid gets generated for a smartlink created using IMIconnect.
validityNumberNoSpecifies 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"
    }
  ]
}
Language
Authorization
Header