IMIconnect Developer Hub

Welcome to the IMIconnect developer hub. You'll find all the resources to help you get started with IMIconnect quickly. We are here to support you if you get stuck. Let's jump right in!

Get Started
 

IMIconnect provides multi-channel Messaging, Profile Management, Transaction Status, and Event Trigger APIs for setting up and delivering intelligent services.

The table below details the IMIconnect APIs.

Reference information for these APIs such as return codes and glossary definitions can be found here:

 

The Messaging API is a single API with individual channel objects that allows third party/external applications to make outbound messaging requests using a RESTful API over HTTPS to the IMIconnect platform.

Each request can send one or multiple messages based on the definition of destination array in the API. Each API request can be customised with a set of parameters.

You can send batch messages on multiple channels with a single API request. For example, a bank can send a personalised greeting message to its customers using the delivery channel as SMS.
Using batch message API request, you can send messages up to 1000 destinations.

Channels covered by the Messaging API are:

  • SMS
  • Voice
  • Push
  • Android
  • iOS
  • Web
  • Appmessaging (Real Time App-Messaging)
  • OTT-Messaging
  • Facebook
  • Twitter
  • WeChat

Prerequisites:

Following are the prerequisites to send and receive messages using Messaging API:

  • A login credentials to access IMIconnect.
  • A service created must be in Live state.
  • A Service Key must be passed with every API request in header. For more details on how to obtain a Service Key, see service creation section.

API parameters

For data privacy and security reasons, standard HTTP is not supported; REST API is served over encrypted HTTPS.

Parameter
Type
Mandatory
Description

deliverychannel

String

Yes

Specifies the channel to send a message. (sms/voice/push/rt/fb/twitter/wechat).

destination

JSONArray

Yes

The destination parameter is a sub-parameter array of strings. This allows multiple destinations.

channels

JSONArray

Yes

The channel parameter encompasses sub-parameters.

message

JSONObject

No

This parameter is used when the message consisting of a predefined template.

route

String

No

Routing policy to use. The options are:

  • IMMD
  • LCGD
  • LCBE

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

A URL that receives notifications. This overrides the service's Notify URL.

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.

Response / return codes

This API may return the following response codes:

Response Code
Message
Description

1001

Queued

Returned when the request is accepted by IMIconnect.

7000

Invalid JSON

Returned when an invalid JSON request is sent.

7001

Authentication failed

Returned when an invalid service key or profile key is provided in the request.

7002

Service key missing

Returned when the parameter key is missing in the message request.

7003

Mandatory parameters missing

Returned when the mandatory parameters configured in custom event are missing.

7004

Invalid parameters

Returned when the parameters are invalid.

7006

Internal error occurred

Returned when an internal error occurs.

7007

Service inactive

Returned when the service is in inactive state.

7009

Max number of destinations

Returned when an API request exceeds the limit (1000) to send messages using messaging API.

Suggest Edits

SMS

This single API provides a multitude of functionality for multi-channel outbound messaging.

 
posthttps://api.imiconnect.io/resources/v1/messaging
{
  "deliverychannel":"sms",
   "channels":{
     "sms":{
        "text":"Sending first SMS using IMIconnect",
        "senderid":"CONNCT"
     }
   },
    "destination":[
     {
        "msisdn":["91900000009"]
     }
  ]
}
//Example: SMS with Smartlink
{
  "channels":{
    //Smartlink array must be available to replace {{link_<linkid>}} information in this  channel. 
      "smartlinks":[
        {
            "linkid": 5,
            "validity": 30
        }
      ], 
    "sms":{
      "type":1,
      "text":"Sending first SMS with smart link using IMIconnect. Click the link to get surprise gift {{link_5}}",
      "senderid":"CONNCT"
    }
  },
  "destination":[
     {
        "msisdn":["91900000009"]
     }
   ]
}
{
  "correlationid":"sgh3tvk",
  "notifyurl":"https://mywebsite.com/record/transactions",
  "notifydata":"kopwest4kfr",
  "expiry":"2015-04-12T18:51:19",
  "priority":"2",
  "deliverychannel":"sms",
   "channels":{
     "smartlinks":[
        {
            "linkid": 5,
            "validity": 30
        }
      ],
     "sms":{
        "text":"Sending first SMS with smart link using IMIconnect. Click the link to get surprise gift {{link_5}}",
        "senderid":"CONNCT"
     }
   },
    "destination":[
     {
        "msisdn":["91900000009"],
        "correlationid":"sgh3tvkpert"
     }
  ]
}
[{
        "deliverychannel": "sms",
        "channels": {
            "sms": {
                "text": "Hi John, Greetings from MNOP bank. "
            }
        },
        "destination": [{
            "msisdn": ["91900000009"]
        }]
    }, {
        "deliverychannel": "sms",
        "channels": {
            "sms": {
                "text": "Hi Mark, Greetings from MNOP bank. "
            }
        },
        "destination": [{
            "msisdn": ["91900000008"]
        }]
    }, {
        "deliverychannel": "sms",
        "channels": {
            "sms": {
                "text": "Hi steve, Greetings from MNOP bank. "
            }
        },
        "destination": [{
            "msisdn": ["91900000007"]
        }]
    }

]
A binary file was returned

You couldn't be authenticated

No response examples available
 

Request

Request Headers

The following table describes the request headers:

Request Header
Description

key

Service Key

content-type

application/json

Parameters

The following are the parameters of the request body:

Parameter
Type
Mandatory
Description

deliverychannel

String

Yes

Specifies the channel to send a message. When the channel is set to sms, the messages are limited to 1024 bytes.

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

For more details, refer to channels array.

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.
Message length is limited as per SMS is 1024 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 client-side identifier chosen by the Service Provider to correlate requests and their subsequent responses. The correlationid can be up to 50 bytes long.

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.

More information on notify URL formats, click Message Receipts.

callbackData

String

No

An identifier or data that will be sent 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.

destination

The destination parameter can be a string array of up to 1,000 entries.

Messages can be sent to single or multiple recipients in a single request.

Name
Description

customerid

A customerid is the Client specific unique alphanumerical ID for distinguishing customers. The IMIconnect platform uses this customerid to reference a Customer Profile which may contains one or more customer contact details.

The IMIconnect platform will intelligently match the appropriate communication detail within the context of the current communication method.

msisdn

A msisdn is the Mobile Station International Subscriber Directory Number.

The msisdn is the subscriber number in international format that starts with the country code and continues with the subscribe number (with the leading zero omitted). For instance the UK number 01234567890 becomes 441234567890.

correlationid

A unique transaction ID used by a Client to match requests with responses.

Note: This value will override the correlationid in the request body.

channels

The channels parameter block configures channel communication parameters and will overrides the service's default values and the parameters in the base request.

SMS


The following parameters are part of the sms parameter block which in turn is part of the channels block.

Parameter
Type
Mandatory
Description

text

String

Yes

Text message up to 1024 characters.

senderid

String

No

The Sender ID for this message.

Note: The senderid asset must be pre-configured and associated with the channel. If the senderid is not configured, a default senderid CONNCT can be used to send the message.

media-path

String

No

Media path which appends to the text message.

type

String

No

Following are the supported message types:

  • 1 – Text (default)
  • 2 – Flash
  • 3 – Binary
  • 4 – Unicode

If no parameter is specified, type defaults to Text.

body

String

Yes (when type is set to 3)

When type is set to 3, the body shall contain hexadecimal content for binary type message.

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.

Response / return codes

This API may return the following response codes:

Response Code
Message
Description

1001

Queued

Returned when the request is accepted by IMIconnect.

7000

Invalid JSON

Returned when an invalid JSON request is sent.

7001

Authentication failed

Returned when an invalid service key or profile key is provided in the request.

7002

Service key missing

Returned when the parameter key is missing in the message request.

7003

Mandatory parameters missing

Returned when the mandatory parameters configured in custom event are missing.

7004

Invalid parameters

Returned when the parameters are invalid.

7006

Internal error occurred

Returned when an internal error occurs.

7007

Service inactive

Returned when the service is in inactive state.

7009

Max number of destinations

Returned when an API request exceeds the limit (1000) to send messages using messaging API.

Request Body

{  
   "correlationid":"<Unique transaction ID from the client end>", //Optional
   "notifyurl":"<Notifications will be sent to the URL specified here>", //Optional
   "callbackData":"<Identifier sent alongside notifications to the notifyurl>", //Optional
   "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. >", //Optional
   "priority":"<Accepts numbers 1-low, 2-medium, and 3-high>", //Optional
   "deliverychannel":"sms", //Mandatory
   "message":{  //Optional
      "template":"<Message template ID.>",
      "parameters":{  
         "parameter1":"<value>",
         "parameter2":"<value>",
         "parameter3":"<value>"
         }
      },
      "channels":{  //Mandatory
         "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>"
        }
      ],
         "sms":{  
            "type":"<Message type 1– Text, 2- Flash, 3– Binary, 4– Unicode>",
            "text":"<Channel specific message text>",
            "body":"<Hexadecimal content for binary type message>",
            "media-path":"<Media path which will be appended to SMS text>",
            "senderid":"<Predefined Sender ID for this message>"
         }
      },
      "destination":[  //Mandatory
         {  
            "msisdn/customerid":[  
               "<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.>"
         },
         {  
            "msisdn/customerid":[  
               "<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.>" //Optional
         }
      ]
   
}
{
  "destination":[
    {
      "customerid/msisdn":[
        "<value1>",
        "<value2>"
      ],
      "correlationid":"<Will override correlationid given in request body>"
    },
    {
      "customerid/msisdn":[
        "<value1>",
        "<value2>"
      ],
      "correlationid":"<Will override correlationid given in request body>"
    }
  ]
}
{
  "channels":{
    "sms":{
      "text":"<Channel specific message text>",
      "type":"<Message type 1– Text, 2- Flash, 3– Binary, 4– Unicode>",
      "senderid":"<Predefined Sender ID for this message>",
      "body":"<Hexadecimal content for binary type message>",
      "media-path":"<Media path which will be appended to SMS text>",
            
    }
  }
}
{
  "deliverychannel":"sms",
   "channels":{
     "sms":{
        "text":"Sending first SMS using IMIconnect",
        "senderid":"CONNCT"
     }
   },
    "destination":[
     {
        "msisdn":["91900000009"]
     }
  ]
}
//Example: SMS with Smartlink
{
  "channels":{
    //Smartlink array must be available to replace {{link_<linkid>}} information in this  channel. 
      "smartlinks":[
        {
            "linkid": 5,
            "validity": 30
        }
      ], 
    "sms":{
      "type":1,
      "text":"Sending first SMS with smart link using IMIconnect. Click the link to get surprise gift {{link_5}}",
      "senderid":"CONNCT"
    }
  },
  "destination":[
     {
        "msisdn":["91900000009"]
     }
   ]
}

//Example: Simple SMS including optional parameters
{
  "correlationid":"sgh3tvk",
  "notifyurl":"https://mywebsite.com/record/transactions",
  "notifydata":"kopwest4kfr",
  "expiry":"2015-04-12T18:51:19",
  "priority":"2",
  "deliverychannel":"sms",
   "channels":{
     "smartlinks":[
        {
            "linkid": 5,
            "validity": 30
        }
      ],
     "sms":{
        "text":"Sending first SMS with smart link using IMIconnect. Click the link to get surprise gift {{link_5}}",
        "senderid":"CONNCT"
     }
   },
    "destination":[
     {
        "msisdn":["91900000009"],
        "correlationid":"sgh3tvkpert"
     }
  ]
}

Response Format

{
  "response": [
    {
      "code": "1001",
      "description": "Queued",
      "transid": "f9793c83-f0b7-4200-99d9-20111c507baf",
      "correlationid": "cid"
    }
  ]
}  
Suggest Edits

Voice

This single API provides a multitude of functionality for multi-channel outbound messaging.

 
posthttps://api.imiconnect.io/resources/v1/messaging
 

Request

The messaging request is specified as follows:

Request Headers

The following table describes the request headers:

Request Header
Description

key

Service Key

content-type

application/json

Parameters

The following are the parameters of the request body:

Parameter
Type
Mandatory
Description

deliverychannel

String

Yes

Specifies the channel to make a voice call. The option is voice.

JSONArray

Yes

The destination parameter is an array of up to 1,000 entries. Calls can be made to single or multiple recipients in a single request. For more details, refer to destination array.

JSONArray

Yes

For more details, refer to channels array.

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.

String

No

A client-side identifier chosen by the Service Provider to correlate requests and their subsequent responses. The correlationid can be up to 50 bytes long.

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.

More information on notify URL formats, click Message Receipts.

callbackData

String

No

An identifier or data that will be sent 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.

destination

The destination parameter can be a string array of up to 1,000 entries.

Messages can be sent to single or multiple recipients in a single request.

Name
Description

customerid

A customerid is the Client specific unique alphanumerical ID for distinguishing customers. The IMIconnect platform uses this customerid to reference a Customer Profile which may contains one or more customer contact details.

The IMIconnect platform will intelligently match the appropriate communication detail within the context of the current communication method.

msisdn

A msisdn is the Mobile Station International Subscriber Directory Number.

The msisdn is the subscriber number in international format that starts with the country code and continues with the subscribe number (with the leading zero omitted). For instance the UK number 01234567890 becomes 441234567890.

correlationid

A unique transaction ID used by a Client to match requests with responses.

Note: This value will override the correlationid in the request body.

channels

The channels parameter block configures channel communication parameters and will overrides the service's default values and the parameters in the base request.

voice


The following parameters are part of the voice parameter block which in turn is part of the channels block.

Either one of 'callflowid' or 'media' must be provided for sending a voice message.

Parameter
Type
Mandatory
Description

callflowid

String

Yes*

The callflowid created for voice flow using flow builder.

If specified, the IVR flow setup is used for sending the voice message.

Note: *If 'callflowid' is specified, 'media' field must not be used.

media

String

Yes*

Prompt ID of the audio file uploaded in Tools > Voice media.

Each file uploaded into the voice media folders on the UI is assigned a unique prompt id.

If specified, the audio file located in the specified path is used to send the voice message.

Note: *If 'media' is specified, 'callflowid' field must not be used.

cli

String

No

Caller Line ID to initiate the call.

Note: Contact support@imiconnect.com for more info on setting up your own custom CLI.

Response Format

Request Body

{  
   "correlationid":"<Unique transaction ID from the client end>", //Optional
   "notifyurl":"<Notifications will be sent to the URL specified here>", //Optional
   "callbackData":"<Identifier sent alongside notifications to the notifyurl>", //Optional
   "expiry":"<Expiry time in UTC format, after which messages will not be pushed. Example, 2015-04-12T13:00:19.456Z or 2015-04-12T18:30:19.456+5:30 >", //Optional
   "priority":"<Accepts numbers 1-low, 2-medium, and 3-high>", //Optional
   "deliverychannel":"voice", //Mandatory
      "channels":{  //Mandatory
           "voice":{
             "callflowid":"<Call Flow ID (Created in Call Flow Builder).>",
             "media":"<Name of media item (uploaded in IMIconnect UI).>",
             "cli":"<Predefined Caller Line Identity to initiate the call.>"
        }
      },
      "destination":[  //Mandatory
         {  
            "msisdn/customerid":[  
               "<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.>"
         },
         {  
            "msisdn/customerid":[  
               "<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.>" //Optional
         }
      ]
   
}
{
  "destination":[
    {
      "customerid/msisdn":[
        "<value1>",
        "<value2>"
      ],
      "correlationid":"<Will override correlationid given in request body>"
    },
    {
      "customerid/msisdn":[
        "<value1>",
        "<value2>"
      ],
      "correlationid":"<Will override correlationid given in request body>"
    }
  ]
}
{
  "channels":{
    "voice":{
      "callflowid":"<Call Flow ID (Created in Call Flow Builder).>",
      "media":"<Name of media item (uploaded in IMIconnect UI).>",
      "cli":"<Predefined Caller Line Identity to initiate the call.>"
    }
  }
}
//Simple voice call
{
    "deliverychannel": "voice",
    "channels": {
        "voice": {
            "callflowid": "184",  //The voice flowid assgined by the flow builder
            "cli": "0453745878"
        }
    },
    "destination": [{
        "customerid": [
            "54"
        ]
    }]
}
{
	"deliverychannel":"voice",
    "channels":{
      "voice":{
        
        "media":"354"  //Prompt ID of the uploaded audio file
       
        }},
    "destination": [{
        "customerid": [
            "54"
        ]
    }]
}
{
  "response": [
    {
      "code": "1001",
      "description": "Queued",
      "transid": "f9793c83-f0b7-4200-99d9-20111c507baf",
      "correlationid": "cid"
    }
  ]
}  
Suggest Edits

Appmessaging

This single API provides a multitude of functionality for multi-channel outbound messaging.

 
posthttps://api.imiconnect.io/resources/v1/messaging
 

Request

The messaging request is specified as follows:

Request Headers

The following table describes the request headers:

Request Header
Description

key

Service Key

content-type

Application/JSON

Parameters

The following are the parameters of the request body:

Parameter
Type
Mandatory
Description

deliverychannel

String

Yes

Specifies the channel to send a message.Real Time channel sends messages to enable mobile apps to provide App-Messaging.

It supports rich multimedia messages with text and optional multimedia items.

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.

JSONArray

Yes

For more details, refer to channels array.

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.

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 client-side identifier chosen by the Service Provider to correlate requests and their subsequent responses. The correlationid can be up to 50 bytes long.

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

An identifier or data that will be sent 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.

destination

The destination parameter can be a string array of up to 1,000 entries.

Messages can be sent to single or multiple recipients in a single request.

Name
Description

customerid

A customerid is the Client specific unique alphanumerical ID for distinguishing customers. The IMIconnect platform uses this customerid to reference a Customer Profile which may contains one or more customer contact details.

The IMIconnect platform will intelligently match the appropriate communication detail within the context of the current communication method.

msisdn

A msisdn is the Mobile Station International Subscriber Directory Number.

The msisdn is the subscriber number in international format that starts with the country code and continues with the subscribe number (with the leading zero omitted). For instance the UK number 01234567890 becomes 441234567890.

email

Destination specific ID.

android_pushid

Specifies the Android push ID.

ios_pushid

Specifies the iOS push ID.

chrome_pushid

Specifies the Chrome push ID.

firefox_pushid

Specifies the Firefox push ID and key. The format is pushid@key.

safari_pushid

Specifies the Safari push ID.

psid

Destination specific ID.

twitterid

Destination specific ID.

wechat_user_id

Destination specific ID.

correlationid

A unique transaction ID used by a Client to match requests with responses.

Note: This value will override the correlationid in the request body.

topic

Specifies the topic ID that is created by topic API.

segment

Specifies the segment ID that is created by segment API.

Channels

The channels parameter block configures channel communication parameters and will override the service's default values and the parameters in the base request.

appmessaging


The following parameters are part of the appmessaging parameter block which in turn is part of the channels block.

Parameter
Type
Mandatory
Description

message

JSONObject

Yes

For more information, see message.

notification

JSONObject

No

For more information, see notification.

thread_type

String

Yes

Specifies the thread type.

thread_title

String

Yes

Specifies the thread title.

message


The following table defines the parameters in the message object block.

Parameter
Type
Mandatory
Description

text

String

Yes

Specifies the message.

attachment

JSONObject

No

The attachments parameter is in itself an object parameter block for the following sub-parameters:

  • contentType
  • file
  • preview
  • size
  • duration
  • latitude
  • longitude

For more information on attachment, see attachment.

notification


The following table defines the parameters in the notification block object block.

Parameter
Type
Mandatory
Description

title

String

Yes

Specifies the notification title.

text

String

Yes

Specifies the notification text.

android_extras

JSONObject

No

The following keys are available under android_extras:

For detailed information, see Push:Android.

ios_extras

JSONObject

No

The following keys are available under ios_extras:

For detailed information, see
Push:iOS.

windows_extras

JSONObject

No

The following keys are available under windows_extras:

For detailed information, see
Push:Windows.

web_extras

JSONObject

No

The following keys are available under web_extras:

  • collapsekey
  • action
  • url

For detailed information, see
Push:Web.

interactive

JSONObject

No

For more information, see Section: Interactive.

notificationaction


The following parameters are part of the notificationaction parameter block.

Parameter
Type
Mandatory
Description

action

String

No

Following are the actions you can configure:

  • 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.

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.

attachment


The following parameters are part of the attachment which is part of message block.
Messaage block is in turn part of appmessaging.

Parameter
Type
Mandatory
Description

contentType

String

Yes

MIME content type, such as image/jpg for JPEG images.

Supported content types:

  • file

  • image

  • video

  • audio

  • location

file

String

Yes

Complete URL of file.

preview

String

No, unless contentType is video.

A base64 string of a JPEG image to display as a preview for video.

size

Integer

No

Size of content in bytes.

duration

String

No, unless contentType audio or video

Duration of audio or video in seconds.

latitude

String

No, unless contentType is location

Specifies the latitude of the location.

longitude

String

No, unless contentType is location

Specifies the longitude of the location.

interactive


The following parameters are part of the interactive parameter block which in turn is part of the notification block.

Parameter
Type
Mandatory
Description

pushref

String

No

Define if the sender intends to use the message interaction result as a trigger for rules.

category

String

Yes

The category can be one of the following:

  • 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

  • DOUBLE_REPLY_DISMISS

  • DOUBLE_REPLY_NO_DISMISS

  • DOUBLE_REPLY_YES_DISMISS

  • DOUBLE_REPLY_YES_NO

Where the option is prefixed with SINGLE, only one choice is available. In the case of DOUBLE, two choices are available. In either case the actions parameter depends on the parameter set for category.

actions

JSONArray

Yes

Using the actions parameter, interactive actions can be built.

The actions parameter is a parameter array block consisting of:

  • pos

  • action

  • value

Note: Depending on the category choice, the outcome of the actions parameter varies.

interactive > actions parameter array block

The following parameters are part of the actions parameter array block which in turn is part of the interactive block within the rt block.

Parameter
Type
Mandatory
Description

pos

String

Yes

A numerical value that places the interactive element in the position specified.

action

String

Yes

Action to perform when interaction takes place, for instance:

  • 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)

  • TRIVIAL_REPLY

  • INLINE_REPLY

value

String

Yes, depending on action parameter.

For certain actions, the value of value is used to complete 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:

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.

Response Format

Request Body

{
    "correlationid": "<Unique transaction ID from the client end>", //Optional
    "notifyurl": "<Notifications will be sent to the URL specified here>", //Optional
    "callbackData": "<Identifier sent alongside notifications to the notifyurl>", //Optional
    "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.>", //Optional
    "priority": "<Accepts numbers 1-low, 2-medium, and 3-high>", //Optional
    "message": { //Optional
        "template": "<Message template ID.>",
        "parameters": {
            "parameter1": "<value>",
            "parameter2": "<value>",
            "parameter3": "<value>"
        }
    },
    "deliverychannel": "appmessaging", //Mandatory
    "channels": {
        "appmessaging": {
            "message": {
                "text": "RTM_message",
                "attachment": {
                    "file": "<URL of resource, e.g. http://ip/image.jpg>",
                    "contentType": "image",
                    "size": "10"
                }
            },
            "notification": {
                "web_extras": {
                    "collapse_key": "web_col_key",
                    "action": "web_col_key",
                    "url": "<Valid http URL>"
                },
                "title": "notification_title",
                "text": "notification_text",
                "windows_extras": {
                    "logo": "<URL of resource, e.g. http://ip/image.jpg>",
                    "sound": "wind_not_sound",
                    "image": "<URL of resource, e.g. http://ip/image.jpg>",
                    "badge": "wnd_badge",
                    "notificationaction": {
                        "action": "OPEN_URL",
                        "value": "<Valid HTTP URL>"
                    }
                },
                "interactive": {
                    "category": "DOUBLE_YES_NO",
                    "pushref": "pu_ref",
                    "actions": [{
                            "action": "OPEN_APP",
                            "identifier": "YES",
                            "pos": 1
                        }, {
                            "action": "OPEN_APP",
                            "identifier": "NO",
                            "pos": 2
                        }
                    ]
                },
                "ios_extras": {
                    "attachmenturl": "<URL of resource, e.g. http://ip/image.jpg>",
                    "collapse_key": "ios_col_key",
                    "sound": "ios_ex_sound",
                    "badge": "ios_badge_",
                    "notificationaction": {
                        "action": "OPEN_URL",
                        "value": "<Valid HTTP URL>"
                    }
                },
                "android_extras": {
                    "collapse_key": "and_col_key",
                    "sound": "android_not_sound",
                    "iconurl": "<URL of resource, e.g. http://ip/image.jpg>",
                    "customtags": {
                        "imageurl": "and_not_image"
                    },
                    "notificationaction": {
                        "action": "OPEN_URL",
                        "value": "<Valid HTTP URL>"
                    }
                }
            },
            "thread_type": "conversation",
            "thread_title": "thread_title"
        }
    },
    "destination": [//Mandatory
        {
            "msisdn/customerid": [
                "<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.>"
        }, {
            "customerid": [
                "<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.>"
        }
    ]
}
{
  "destination":[
    {
      "customerid/msisdn/email/psid/android_pushid/ios_pushid/chrome_pushid/firefox_pushid/safari_pushid/twitterid/wechat_user_id":[
        "<value1>",
        "<value2>"
      ],
      "correlationid":"<Will override correlationid given in request body>"
    },
    {
      "customerid/msisdn/email/psid/android_pushid/ios_pushid/chrome_pushid/firefox_pushid/safari_pushid/twitterid/wechat_user_id":[
        "<value1>",
        "<value2>"
      ],
      "correlationid":"<Will override correlationid given in request body>"
    }
  ]
}
{
    "deliverychannel": "appmessaging",
    "channels": {
        "appmessaging": {
            "text": "Hello",
            "attachments": [{
                "file": "https://upload.wikimedia.org/wikipedia/5/59/IMImobile_logo.svg/1280px-IMImobile_logo.png",
                "contentType": "image"
            }]
        }
    },
    "destination": [{
        "customerid": ["9799"]
    }]
}
{
    "deliverychannel": "appmessaging",
    "channels": {
        "smartlinks": [{
            "linkid": 5,
            "validity": 30
        }],
        "appmessaging": {
            "text": "RT message with Smartlinks and attachment as image {{link_5}}",
            "attachments": [{
                "file": "https://upload.wikimedia.org/5/59/IMImobile_logo.svg/1280px-IMImobile_logo.png",
                "contentType": "image"
            }]
        }
    },
    "destination": [{
        "customerid": ["9799"]
    }]
}
{
    "deliverychannel": "appmessaging",
    "channels": {
            "appmessaging": {
            "message": {
            "text": "message"
            },
            "notification": {
               "title": "notification_title",
                "text": "notification_text",
                "interactive": {
                    "category": "DOUBLE_YES_NO",
                    "pushref": "pushRef123",
                    "actions": [
                        {
                           "action": "OPEN_APP",
                           "identifier": "YES",
                           "pos": 1
                        },
                        {
                           "action": "OPEN_APP",
                           "identifier": "NO",
                           "pos": 2
                        }
                    ]
                }
            },
            "thread_type": "conversation_thread_name",
            "thread_title": "conversation_title1"
        },
    "destination": [{
        "customerid": [
            "54"
        ]
    }]
}
{
  "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": [
    {
      "code": "1001",
      "description": "Queued",
      "transid": "f9793c83-f0b7-4200-99d9-20111c507baf",
      "correlationid": "cid"
    }
  ]
}  
posthttps://api.imiconnect.io/resources/v1/messaging
 

Request

The messaging request is specified as follows:

Request Headers

The following table describes the request headers:

Request Header
Description

key

Service Key

content-type

application/json

Request 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.

destination

The destination parameter can be a string array of up to 1,000 entries.

Messages can be sent to single or multiple recipients in a single request.

Name
Description

customerid

A customerid is the Client specific unique alphanumerical ID for distinguishing customers. The IMIconnect platform uses this customerid to reference a Customer Profile which may contains one or more customer contact details.

The IMIconnect platform will intelligently match the appropriate communication detail within the context of the current communication method.

msisdn

A msisdn is the Mobile Station International Subscriber Directory Number.

The msisdn is the subscriber number in international format that starts with the country code and continues with the subscribe number (with the leading zero omitted). For instance the UK number 01234567890 becomes 441234567890.

email

Destination specific ID.

android_pushid

Specifies the Android push ID.

ios_pushid

Specifies the iOS push ID.

chrome_pushid

Specifies the Chrome push ID.

firefox_pushid

Specifies the Firefox push ID and key. The format is pushid@key.

safari_pushid

Specifies the Safari push ID.

psid

Destination specific ID.

twitterid

Destination specific ID.

wechat_user_id

Destination specific ID.

correlationid

A unique transaction ID used by a Client to match requests with responses.

Note: This value will override the correlationid in the request body.

topic

Specifies the topic ID that is created by topic API.

userid

Represents the unique id for an app user given by Client while appuser registration.

segment

Specifies the segment ID that is created by segment API.

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

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

priority

Integer

No

A value from 1 to 5, where 5 is the highest. The default value is 3.

title

String

No

Message title.

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

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.

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.

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:

  • badge

  • sound

  • time_to_live

  • silentpush

  • url

  • html

  • customtags

  • notificationaction

  • collapse_key

  • attachmenturl

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

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.

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:

  • time_to_live

  • collapse_key

  • customtags

Note: The parameter collapse_key is not applicable to safari browser.

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.

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

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.

Response 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.>"
    }, {
        "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.>"
    }]
}
{
  "destination":[
    {
      "customerid/msisdn/email/psid/android_pushid/ios_pushid/chrome_pushid/firefox_pushid/safari_pushid/twitterid/wechat_user_id":[
        "<value1>",
        "<value2>"
      ],
      "correlationid":"<Will override correlationid given in request body>"
    },
    {
      "customerid/msisdn/email/psid/android_pushid/ios_pushid/chrome_pushid/firefox_pushid/safari_pushid/twitterid/wechat_user_id":[
        "<value1>",
        "<value2>"
      ],
      "correlationid":"<Will override correlationid given in request body>"
    }
  ]
}
{
    "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>"
                }]
            }
        }
    }
}
{
  "channels":{
    "push":{
      "android":{
        "text":"<Android message>",
        "title": "android message title",
        "extras":{Refer to Android extras}
      }
    }
  }
{
   "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"
		}
}
{
  "channels":{
    "push":{
      "ios":{
        "text":"<iOS message>",
        "title": "ios message title",
        "extras":{Refer to ios extras}
      }
    }
  }
{
    "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"
    }
}
{
    "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"]
            }
        }

    }
}
{
  "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": [
    {
      "code": "1001",
      "description": "Queued",
      "transid": "f9793c83-f0b7-4200-99d9-20111c507baf",
      "correlationid": "cid"
    }
  ]
}  
Suggest Edits

OTT-Messaging

This single API provides a multitude of functionality for multi-channel outbound messaging

 
posthttps://api.imiconnect.io/resources/v1/messaging
 

Request

The messaging request is specified as follows:

Request Headers

The following table describes the request headers:

Request Header
Description

key

Service Key

content-type

application/json

Parameters


The following are the parameters of the request body:

Parameter
Type
Mandatory
Description

deliverychannel

String

Yes

Specifies the channel to send a message.

{
    "deliverychannel":"  <fb/twitter/wa/wechat>"    
}

JSONArray

Yes

The destination parameter is a sub-parameter array of strings. This allows multiple destinations.

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.

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.

destination

The destination parameter can be a string array of up to 1,000 entries.

Messages can be sent to single or multiple recipients in a single request.

Name
Description

customerid

A customerid is the Client specific unique alphanumerical ID for distinguishing customers. The IMIconnect platform uses this customerid to reference a Customer Profile which may contains one or more customer contact details.

The IMIconnect platform will intelligently match the appropriate communication detail within the context of the current communication method.

msisdn

A msisdn is the Mobile Station International Subscriber Directory Number.

The msisdn is the subscriber number in international format that starts with the country code and continues with the subscribe number (with the leading zero omitted). For instance the UK number 01234567890 becomes 441234567890.

email

Destination specific ID.

android_pushid

Specifies the Android push ID.

ios_pushid

Specifies the iOS push ID.

chrome_pushid

Specifies the Chrome push ID.

firefox_pushid

Specifies the Firefox push ID and key. The format is pushid@key.

safari_pushid

Specifies the Safari push ID.

psid

Destination specific ID.

twitterid

Destination specific ID.

wechat_user_id

Destination specific ID.

correlationid

A unique transaction ID used by a Client to match requests with responses.

Note: This value will override the correlationid in the request body.

deliverychannel

The deliverychannel value determines the channel to use for delivering messages. The deliverychannel value may be one of the following:

Channel
Description

sms

Short Messaging Service.

voice

Voice services.

push

Push messaging service

appmessaging

Real Time channel that sends messages to enabled mobile apps to provide App-Messaging.

Supports rich multimedia messages with text and optional multimedia items.

fb

Facebook

twitter

Twitter

wechat

WeChat

channels


The channels parameter block configures channel communication parameters and will overrides the service's default values and the parameters in the base request.

OTT-Messaging

The OTT-Messaging channel consists of modern social networks that use IP networks to communicate. As such these channels tend to be more cost effective to use. The following social networks are part of OTT-Messaging:

The following parameters are part of the OTT-Messaging parameter block which in turn is part of the channels block.

You must pass at least one parameter in the messaging block.

Parameter
Type
Mandatory
Description

fb

JSONObject

No

Social network, contains sub-parameters:

  • text

  • attachment

  • sender_action

  • notification_type

  • quick_replies

twitter

JSONObject

No

Social network, contains sub-parameters:

  • text

wa

JSONObject

No

Social network, contains sub-parameters:

  • text

wechat

JSONObject

No

Social network, contains sub-parameters:

  • text

  • attachment

Facebook


The following parameters are part of the fb parameter block which in turn is part of the OTT-Messaging block.

Parameter
Type
Mandatory
Description

text

String

Yes

Specifies the message text. Note: Either text or attachment or sender_action is mandatory.

attachment

JSONObject

Yes

A block consists of the following parameters:

  • type

  • payload

Note: Either text or attachment or sender_action is mandatory.

notification_type

String

No

Specifies the notification to be received with a sound or without sound. The options are:

  • REGULAR (Default): The notification will be sent with a sound.

  • SILENT_PUSH: the notification will be sent silently. The notification will be received without any sound.

  • NO_PUSH: The notification will not be sent.

sender_action

String

Yes

Specifies the message state. The options are:

  • mark_seen

  • typing_on

  • typing_off

Note: Either text or attachment or sender_action is mandatory.

quick_replies

JSONArray

No

Specifies an options in the text message to reply back to the sender. When the quick reply is tapped, the message is sent with the option tapped. Once the message is sent, the options disappear.

Facebook - Sender Action


Sender action feature allows you to set typing indicators or send read receipts to let users know that someone is typing or the message is read. Typically this feature is used in chat conversations. When you are processing a time consuming request, you can send a typing indicator. The typing indicator gives an impression to your users that someone is replying to their request. For more information on sender action, click here.

Facebook - Quick Replies


Quick Replies are buttons with some text that appears above the text composer. Users can tap on the button to respond to the message. Once the message is tapped, the options disappear. You can add up to 10 buttons. These buttons are useful to get a specific response from the users. You can configure buttons to have a plain text or a combination of text and image. You can also configure a button with location, so that users can send geographic location in the conversation. You can configure the button with a payload that can have custom data that will be sent back to the enterprises through a webhook. For additional information on Quick Replies, click here.

Parameter
Type
Mandatory
Description

content_type

String

Yes

Specifies the type of content. The options are:

  • text

  • location

title

String

Yes. This is applicable only when content_type is set as text.

Specifies the caption for button. You can add upto 20 characters as title.

payload

String

Yes. This is applicable only when content_type is set as text.

Specifies the custom data that will be sent back to you through webhook. The limit of this payload is 1000 characters.

image_url

String

No

Specifies the URL of the image sent as quick_replies.

Facebook - Attachment


Specifies the attachment type.

Parameter
Type
Mandatory
Description

type

String

Yes

Specifies the type of the attachment. The options are:

  • image

  • audio

  • video

  • file

  • template

payload

JSONObject

Yes

Specifies the payload of attachment. The parameters of payload are:

Facebook - Generic Template


Generic template allows you to send horizontal scrollable set of images with an option to configure short description and buttons to request input from the users. You can add up to 10 images per message. For more information on generic template, click here.

The parameters of generic template are:

Parameter
Type
Mandatory
Description

title

String

Yes

Specifies the bubble title. It has a limit of 80 characters.

item_url

String

No

Specifies the URL that is opened when bubble is tapped.

image_url

String

No

Specifies the bubble image.

subtitle

String

No

Specifies the bubble subtitle. It has a limit of 80 characters.

buttons

JSONArray

No

Specifies a set of buttons that appears as call-to-actions. You can add up to 3 buttons only. The parameters are:

  • type

  • title

  • url

  • payload

Facebook Buttons


Specifies a set of buttons that appears as call-to-actions. You can add up to 3 buttons only. The parameters are:

Parameter
Type
Mandatory
Description

type

String

Yes

Specifies the value for button. The options are:

  • web_url

  • postback

title

String

Yes

Specifies the button title.

url

String

Yes

Specifies the web_url for buttons. It opens a browser when the button is tapped.

payload

String

Yes

When the postback button is clicked an event is raised that can be used to write rules.

Facebook - Button Template


Button template allows you to send a text and buttons attachment to request input from the user. The buttons can open a URL or make a back-end call to your webhook. For more information on button template, click here.

The parameters of button template are:

Parameter
Type
Mandatory

text

String

Yes

The text that appears in the main body.

buttons

JSONArray

No

Specifies a set of buttons that appears as call-to-actions. Click here to view the button object.

Facebook - Receipt Template


Receipt template allows you to send order confirmation, with the transaction summary and description for each item. For more information on receipt template, click here.

The parameters of receipt template are:

Parameter
Type
Mandatory
Description

recipient_name

String

Yes

Specifies the recipients name.

order_number

String

Yes

specifies the order number.

currency

String

Yes

Specifies the currency for order.

payment_method

String

Yes

Specifies the payment method details.

timestamp

String

No

Specifies the timestamp of order. It must be a unique number.

order_url

String

No

Specifies the URL of order.

JSONArray

Yes

Specifies the details of the order. The parameters are:

  • title

  • subtitle

  • quantity

  • price

  • currency

  • image_url

JSONObject

No

Specifies the details of the shipping address. The parameters are:

  • street_1

  • street_2

  • city

  • postal_code

JSONObject

Yes

Specifies the payment summary details. The parameters are:

  • subtotal

  • shipping_cost

  • total_tax

JSONArray

No

Specifies the payment adjustments. The parameters are:

  • name

  • amount

Facebook - Receipt Elements

Specifies the details of the order in receipt template. It accepts an array.

Parameter
Type
Mandatory
Description

title

String

Yes

Specifies the title of the item.

subtitle

String

No

Specifies the sub title of item.

quantity

Integer

No

Specifies the quantity of item.

price

Double

No

Specifies the item price.

currency

String

No

Specifies the currency of price.

image_url

String

No

Specifies the image URL of item.

Facebook - Receipt Address

Specifies the details of the shipping address.

Parameter
Type
Mandatory
Description

street_1

String

Yes

Specifies the street address, line 1.

street_2

String

No

Specifies the street address, line 2.

city

String

Yes

Specifies the city details.

postal_code

String

Yes

Specifies the postal code.

state

String

Yes

Specifies the state abbreviation of a country.

country

String

Yes

Specifies the two letter abbreviation of a country.

Facebook - Receipt Summary

Specifies the payment summary details. The parameters are:

Parameter
Type
Mandatory
Description

subtotal

Number

No

Specifies the subtotal.

shipping_cost

Number

No

Specifies the cost of shipping.

total_tax

Number

No

Specifies the total tax.

total_cost

Number

No

Specifies the total cost.

Facebook - Receipt Adjustments

Specifies the payment adjustments. The parameters are:

Parameter
Type
Mandatory
Description

name

String

No

Specifies the name of adjustment.

amount

Number

No

Specifies the adjusted amount.

Facebook - Airline Itinerary Template


Airline itinerary template is used send airline itinerary and receipt. For more information on airline boarding pass template, click here.

The parameters of payload object are:

Parameter
Type
Mandatory
Description

template_type

String

Yes

Specifies the template type. The value must be airline_itinerary.

intro_message

String

Yes

Specifies the introduction message.

locale

String

Yes

Specifies the two-letter language region code. For example, en_US.

theme_color

String

No

Specifies the background color of the attachment. The format must be RGB hexadecimal string. The default value is #009ddc.

pnr_number

String

Yes

Specifies the passenger name record number.

JSONArray

Yes

Specifies an array of passenger information. Refer to passenger_info object.

JSONArray

Yes

Specifies the flight information. Refer to flight_info object.

JSONArray

Yes

Specifies the information unique to passenger or segment pair. Refer to passenger_segment_info object.

price_info

JSONArray

No

Specifies the itemized price information. Refer to price_info object.

base_price

Number

No

Specifies the base price amount.

tax

Number

No

Specifies the tax amount.

total_price

Number

Yes

Specifies the total price of the booking.

currency

String

Yes

Specifies the currency code. For example, to display American dollars the code is USD.

Click here to view the supported list of currencies.

Facebook - Airline Itinerary Template - Passenger_info

The parameters of passenger_info under Airline Itinerary template are:

Parameter
Type
Mandatory
Description

passenger_id

String

Yes

Specifies a unique passenger identification.

ticket_number

String

No

Specifies the ticket number.

name

String

Yes

Specifies the full name of the passenger.

Facebook - Airline Itinerary Template - Flight_info

The parameters of flight_info under Airline Itinerary template are:

Parameter
Type
Mandatory
Decription

connection_id

String

Yes

Specifies a unique id within the ininerary to group segments of a connection together.

segment_id

String

Yes

Specifies the segment_id of the passenger_segment_info object.

flight_number

String

Yes

Specifies the flight number.

aircraft_type

String

No

Specifies the aircraft type.

departure_airport

JSONObject

Yes

Specifies the departure airport. Refer to airport object.

arrival_airport

JSONObject

Yes

Specifies the arrival airport. Refer to airport object.

flight_airport

JSONObject

Yes

Specifies the schedule for the flight. Refer to flight_schedule object.

travel_class

String

Yes

Specifies the travel class.

Facebook - Airline Itinerary Template - Passenger_segment_info

The parameters of passenger_segment_info under Airline Itinerary template are:

Parameter
Type
Mandatory
Description

segment_id

String

Yes

Specifies a unique id within the itinerary to identify a flight segment.

passenger_id

String

Yes

Specifies the passenger id of passenger_info object.

seat

String

Yes

Specifies the seat number for the passenger.

seat_type

String

Yes

Specifies the seat type for the passenger. For example, Economy comfort.

product_info

String

Yes

Specifies the list of products the passenger purchased. You can add up to 4 products only.

Facebook - Airline Itinerary Template - Airport

The parameters of airport object under Airline Itinerary template are:

Parameter
Type
Mandatory
Description

airport_code

String

Yes

Specifies the airport code.

city

String

Yes

Specifies the city name.

terminal

String

No

Specifies the terminal number.

gate

String

No

Specifies the gate number.

Facebook - Airline Itinerary Template - Flight_schedule

The parameters of flight_schedule object under Airline Itinerary template are:

Parameter
Type
Mandatory
Description

boarding_time

String

No

Specifies the boarding time in departure airport timezone.

departure_time

String

Yes

Specifies the departure time in departure airport timezone.

arrival_time

String

Yes

Specifies the arrival time in arrival airport timezone.

The timezone format must be in ISO 8601-based format YYYY-MM-DDThh:mm. For example, 2016-09-26T11:15.

Facebook - Airline Itinerary Template - price_info

The parameters of price_info object under Airline Itinerary template are:

Parameter
Type
Mandatory
Description

title

String

Yes

Specifies the product title

value

String

Yes

Specifies the product description.

Facebook - Airline Checkin Template


Airline checkin template is used to send flight checkin reminder message. For more information on airline checkin template, click here.

The parameters payload object are:

Parameter
Type
Mandatory
Description

template_type

String

Yes

Specifies the template type. The value must be airline_itinerary.

intro_message

String

Yes

Specifies the introduction message.

locale

String

Yes

Specifies the two-letter language region code. For example, en_US.

theme_color

String

No

Specifies the background color of the attachment. The format must be RGB hexadecimal string. The default value is #009ddc.

pnr_number

String

Yes

Specifies the passenger name record number.

flight_info

JSONArray

Yes

Specifies the flight information. Refer to flight_info object.

checkin_url

String

Yes

Specifies the URL for passengers to check-in.

Facebook - Airline Checkin Template - Flight_Info

The parameters of flight_info under Airline Checkin template are:

Parameter
Type
Mandatory
Description

flight_number

String

Yes

Specifies the flight number.

departure_airport

JSONObject

Yes

Specifies the departure airport.

arrival_airport

JSONObject

Yes

Specifies the arrival airport.

flight_schedule

JSONObject

Yes

Specifies the schedule for the flight.

Facebook - Airline Checkin Template - Flight_schedule

The parameters of flight_schedule object under Airline Checkin template are:

Parameter
Type
Mandatory
Description

boarding_time

String

No

Specifies the boarding time in departure airport timezone.

departure_time

String

Yes

Specifies the departure time in departure airport timezone.

arrival_time

String

Yes

Specifies the arrival time in arrival airport timezone.

The timezone format must be in ISO 8601-based format YYYY-MM-DDThh:mm. For example, 2016-09-26T11:15.

Facebook - Airline Boarding Pass Template


Airline boarding pass template allows you to send boarding passes for one or more flights to passengers. For more information on airline boarding pass template, click here.

The parameters of payload object under Airline Boarding Pass template are:

Parameter
Type
Mandatory
Description

template_type

String

Yes

Specifies the template type. The value must be airline_itinerary.

intro_message

String

Yes

Specifies the introduction message.

locale

String

Yes

Specifies the two-letter language region code. For example, en_US.

theme_color

String

No

Specifies the background color of the attachment. The format must be RGB hexadecimal string. The default value is #009ddc.

boarding_pass

JSONArray

Yes

Specifies the boarding passes for passengers. Refer to the boarding_pass object.

Facebook - Airline Boarding Pass Template - Boarding_Pass

The parameters of boarding_pass object under Airline Boarding Pass template are:

Parameter
Type
Mandatory
Description

passenger_name

String

Yes

Specifies the passenger name.

pnr_number

String

Yes

Specifies the passenger name record number.

travel_class

String

No

Specifies the travel class.
The options are:

  • economy

  • business

  • first_class

seat

String

No

Specifies the seat number for the passenger.

auxiliary_fields

JSONArray

No

Specifies the flexible information to display in the auxiliary section. You can add upto 5 fields. Refer to field object.

secondary_fields

JSONArray

No

Specifies the flexible information to display in the secondary section. You can add upto 5 fields. Refer to field object.

logo_image_url

String

Yes

Specifies the URL for the logo image.

header_image_url

String

No

Specifies the URL for the header image.

header_text_field

String

No

Specifies the text for the header field.

qr_code

String

Yes, unless the image of barcode is provided.

Specifies Aztec or QR code.

barcode_image_url

String

Yes, unless the qr_code is provided.

Specifies the URL of the barcode image.

above_bar_code_image_url

String

Yes

Specifies the URL of thin image above the barcode.

flight_info

JSONObject

Yes

Specifies the information about the flight. Refer to flight_info object.

Facebook - Airline Boarding Pass Template - Flight_info

The parameters of flight_info under Airline Boarding Pass template are:

Parameter
Type
Mandatory
Description

flight_number

String

Yes

Specifies the flight number.

departure_airport

JSONObject

Yes

Specifies the departure airport. Refer to airport object.

arrival_airport

JSONObject

Yes

Specifies the arrival airport. Refer to airport object.

flight_schedule

JSONObject

Yes

Specifies the schedule for the flight. Refer to flight_schedule object.

Facebook - Airline Boarding Pass Template - Flight_schedule

The parameters of flight_schedule object under Airline Boarding Pass template are:

Parameter
Type
Mandatory
Description

boarding_time

String

No

Specifies the boarding time in departure airport timezone.

departure_time

String

Yes

Specifies the departure time in departure airport timezone.

arrival_time

String

No

Specifies the arrival time in arrival airport timezone.

The timezone format must be in ISO 8601-based format YYYY-MM-DDThh:mm. For example, 2016-09-26T11:15.

Facebook - Airline Boarding Pass Template - Flight_info - Airport

The parameters of airport object under Airline Boarding Pass template are:

Parameter
Type
Mandatory
Description

airport_code

String

Yes

Specifies the airport code.

city

String

Yes

Specifies the city name.

terminal

String

No

Specifies the terminal number.

gate

String

No

Specifies the gate number.

The timezone format must be in ISO 8601-based format YYYY-MM-DDThh:mm. For example, 2016-09-26T11:15.

Facebook - Airline Boarding Pass Template - Field

The parameters of field object under Airline Boarding Pass template are:

Parameter
Type
Mandatory
Description

label

String

Yes

Specifies the label for the additional field.

value

String

Yes

Specifies the value for the additional field.

Facebook - Airline Flight Update Template


Airline flight update template allows you to send flight status update message. For more information on airline flight update template, click here.

The parameters payload object are:

Parameter
Type
Mandatory
Description

template_type

String

Yes

Specifies the template type. The value must be airline_update.

intro_message

String

No

Specifies the introduction message.

update_type

String

Yes

Specifies the type of update for the notification. The options are:

  • delay

  • gate_change

  • cancellation

locale

String

Yes

Specifies the two-letter language region code. For example, en_US.

theme_color

String

No

Specifies the background color of the attachment. The format must be RGB hexadecimal string. The default value is #009ddc.

pnr_number

String

Yes

Specifies the passenger name record number.

update_flight_info

JSONObject

Yes

Specifies the information about a flight. Refer to update_flight_info object.

Facebook - Airline Flight Update Template - Update_flight_info

The parameters of update_flight_info under Airline Flight Update template are:

Parameter
Type
Mandatory
Description

flight_number

String

Yes

Specifies the flight number.

departure_airport

JSONObject

Yes

Specifies the departure airport. Refer to airport object.

arrival_airport

JSONObject

Yes

Specifies the arrival airport. Refer to airport object.

flight_schedule

JSONObject

Yes

Specifies the schedule for the flight. Refer to flight_schedule object.

Facebook - Airline Flight Update Template - Update_Flight_info - Flight_schedule

The parameters of flight_schedule under Airline Flight Update template are:

Parameter
Type
Mandatory
Description

boarding_time

String

No

Specifies the boarding time in departure airport timezone.

departure_time

String

Yes

Specifies the departure time in departure airport timezone.

arrival_time

String

No

Specifies the arrival time in arrival airport timezone.

The timezone format must be in ISO 8601-based format YYYY-MM-DDThh:mm. For example, 2016-09-26T11:15.


Twitter


Twitter is an on-line social networking service that enables users to send and read 10000 character messages.

The following parameters are part of the Twitter parameter block which in turn is part of the OTT-Messaging block.

Parameter
Type
Mandatory
Description

text

String

Yes

Specifies the text message.


WeChat


The following parameters are part of the WeChat parameter block which in turn is part of the OTT-Messaging block.

Following are the limitations from WeChat when uploading multimedia files:

  • Image (image): 128K, supports for JPG
  • Audio (voice): 256K, no more than 60s play time, and supports for AMR
  • Video (video): 1MB, supports for MP4
  • Thumb (thumb): 64KB, supports for JPG

To send an attachment, you can upload it using Service > template in IMIconnect or you can upload by other means without using IMIconnect and use the id in the API.

Parameter
Type
Mandatory
Description

text

String

Yes

Message text

attachment

JSONObject

Yes - if template is not passed

Specifies the attachment details that is uploaded by other means without using IMIconnect.

Parameters of attachment object are:

Parameter
Type
Mandatory
Description

type

String

Yes

Specifies the media type. Following the supported types:

  • image

  • voice

  • video

media_id

String

Yes

Specifies the media id that is received for the uploaded file.

thumb_media_id

String

Yes - if type is video

Specifies the preview image media id for the video.

smartlinks

An array that contains the parameters of Smartlink. This is an optional. 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 in Messaging. The link id gets generated when a Smartlink is created in IMIconnect.

validity

Number

No

Specifies the time in minutes after which the link will expire.

Response Body

Response / return codes

This API may return the following response codes:

Response Code
Message
Description

1001

Queued

Returned when the request is accepted by IMIconnect.

7000

Invalid JSON

Returned when an invalid JSON request is sent.

7001

Authentication failed

Returned when an invalid service key or profile key is provided in the request.

7002

Service key missing

Returned when the parameter key is missing in the message request.

7003

Mandatory parameters missing

Returned when the mandatory parameters configured in custom event are missing.

7004

Invalid parameters

Returned when the parameters are invalid.

7006

Internal error occurred

Returned when an internal error occurs.

7007

Service inactive

Returned when the service is in inactive state.

7009

Max number of destinations

Returned when an API request exceeds the limit (1000) to send messages using messaging API.

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.Foe 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":"fb/twitter/wa/wechat",
   "message":{  
      "template":"<Message template ID.>",
      "parameters":{  
         "parameter1":"<value>",
         "parameter2":"<value>",
         "parameter3":"<value>"
          }
      },
      "channels":{
         "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>"
        }
      ],
        "OTT-Messaging":{
          "fb":{
                "attachment": {
                    "type": "<type of attachment: image/template>",
                    "payload": { 
                        "template_type": "<type of template: generic/buttons/receipt>",
                        "elements": [{
                             "title": "<bubble title>",
                             "image_url": "<image url that opens when bubble is tapped>",
                             "subtitle": "<subtitle for a bubble>",
                             "buttons": [{
                                 "type": "<options for button: web_url/postback>",
                                 "url": "<Applicable when button type is web url. Specifies the url that opens in a browser when button is tapped>",
                                 "title": "<url title>",
                                 "payload": "<Applicable when type is postback. A user defined payload that  is used in rules>"
                                }]
                            }

                        ]
                    }
                }       
            },
            "twitter":{
               "text":"<Channel specific message text>"
            },
            "wa":{  
               "text":"<Channel specific message text>"
            },
            "wechat": {//text or attachment must be provided. If you provide both, only text is delivered.
               "text": "<Channel specific message text>",
               "attachment": {//Use this object if you have uploaded media without using IMIconnect. 
               "type": "<Supported file types as attachment image/video/>",
               "media_id": "<Media id received from WeChat for the uploaded file>"
              }
           }
         }
      },
      "destination":[  
         {  
            "customerid/psid/twitterid/wechat_user_id":[  
               "<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.>"
         },
         {  
            "customerid/psid/twitterid/wechat_user_id":[  
               "<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.>"
         }
      ]
   
}
{
  "destination":[
    {
      "customerid/msisdn/email/psid/android_pushid/ios_pushid/chrome_pushid/firefox_pushid/safari_pushid/twitterid/wechat_user_id":[
        "<value1>",
        "<value2>"
      ],
      "correlationid":"<Will override correlationid given in request body>"
    },
    {
      "customerid/msisdn/email/psid/android_pushid/ios_pushid/chrome_pushid/firefox_pushid/safari_pushid/twitterid/wechat_user_id":[
        "<value1>",
        "<value2>"
      ],
      "correlationid":"<Will override correlationid given in request body>"
    }
  ]
}
{
  "deliverychannel":"<fb/twitter/wa/wechat>"
}
{
    "channels": {
        "OTT-Messaging":{
          "fb":{
                "text": "<Channel specific message text>",
                "attachment": {
                    "type": "<type of attachment: image/template>",
                    "payload": { 
                        "template_type": "<type of template: generic/buttons/receipt>",
                        "elements": [{
                                "title": "<bubble title>",
                                "image_url": "<image url that opens when bubble is tapped>",
                                "subtitle": "<subtitle for a bubble>",
                                "buttons": [{
                                    "type": "<options for button: web_url/postback>",
                                    "url": "<Applicable when button type is web url. It opens the browser when the button is tapped>",
                                    "title": "<title for url>",
                                    "payload": "<Applicable when button type is postback. A user defined payload that is used in rules>"
                                }]
                            }

                        ]
                    }
                },
                  "notification_type": "<Options for notification type REGULAR/SILENT_PUSH/NO_PUSH>"//optional parameter. The default option is REGULAR.
            },
          
                "twitter":{
                    "text": "<Channel specific message text>"
                },
                "wa ": {
                    "text": "<Channel specific message text>"
                },
                "wechat": {//Either text or attachment must be provided. If you provide both, only text is delivered.
                    "text": "<Channel specific message text>",
                    "attachment": {//Use this attachment object when you have uploaded  media without using IMIconnect. 
                      "type": "<Supported file types as attachment image/video/>",
                      "media_id": "<Media id received from WeChat for the uploaded file>"
                  }
                }
            }
        }
    }
{
    "deliverychannel": "fb",
    "channels": {
        "OTT-Messaging": {
            "fb": {
              "text": "Welcome to IMIconnect"
            }
        }
    },
    "destination": [{
        "psid": ["1207588322640336"]
    }]
}
{
  "appid": "",
  "notifyurl": "",
  "deliverychannel": "fb",
  "channels": {
    "OTT-Messaging": {
      "fb": {

    "sender_action" : "typing_on"
  }
    }
  },
  "destination": [
    {
      "psid":["1207588322640336"]
    }
  ]
}
{
    "appid": "",
    "notifyurl": "",
    "deliverychannel": "fb",
    "channels": {
        "OTT-Messaging": {
            "fb": {
                "text": "Customer id check 1",
                "quick_replies": [{
                    "content_type": "text",
                    "title": "Red",
                    "payload": "DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_RED"
                }, {
                    "content_type": "text",
                    "title": "Green",
                    "payload": "DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_GREEN"
                }, {
                    "content_type": "text",
                    "title": "Yellow",
                    "payload": "DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_YELLOW"
                }, {
                    "content_type": "text",
                    "title": "Orange",
                    "payload": "DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_ORANGE"
                }, {
                    "content_type": "text",
                    "title": "Pink",
                    "payload": "DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_PINK"
                }, {
                    "content_type": "text",
                    "title": "Brown",
                    "payload": "DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_BROWN"
                }, {
                    "content_type": "text",
                    "title": "Blue",
                    "payload": "DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_BLUE"
                }, {
                    "content_type": "text",
                    "title": "Black",
                    "payload": "DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_BLACK"
                }, {
                    "content_type": "text",
                    "title": "Magenta",
                    "payload": "DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_BLACK"
                }, {
                    "content_type": "text",
                    "title": "Voilate",
                    "payload": "DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_VOILATE"
                }],
                "type": "conversation"
            }
        }
    },
    "destination": [{
        "psid":["1207588322640336"]
    }]
}
{
    "appid": "",
    "notifyurl": "",
    "deliverychannel": "fb",
    "channels": {
        "OTT-Messaging": {
            "fb": {
                "text": "Customer id check 1",
                "quick_replies": [{
                    "content_type": "text",
                    "title": "Red",
                    "payload": "DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_RED",
                    "image_url": "http://www.gstatic.com/webp/gallery/1.jpg"
                }, {
                    "content_type": "text",
                    "title": "Green",
                    "payload": "DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_GREEN",
                    "image_url": "https://www.gstatic.com/webp/gallery3/1.png"
                }, {
                    "content_type": "text",
                    "title": "Yellow",
                    "payload": "DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_YELLOW",
                    "image_url": "https://www.gstatic.com/webp/gallery3/1.png"
                }, {
                    "content_type": "text",
                    "title": "Orange",
                    "payload": "DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_ORANGE",
                    "image_url": "https://www.gstatic.com/webp/gallery3/1.png"
                }, {
                    "content_type": "text",
                    "title": "Pink",
                    "payload": "DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_PINK",
                    "image_url": "https://www.gstatic.com/webp/gallery3/1.png"
                }, {
                    "content_type": "text",
                    "title": "Brown",
                    "payload": "DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_BROWN",
                    "image_url": "https://www.gstatic.com/webp/gallery3/1.png"
                }, {
                    "content_type": "text",
                    "title": "Blue",
                    "payload": "DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_BLUE",
                    "image_url": "https://www.gstatic.com/webp/gallery3/1.png"
                }, {
                    "content_type": "text",
                    "title": "Voilate",
                    "payload": "DEVELOPER_DEFINED_PAYLOAD_FOR_PICKING_VOILATE",
                    "image_url": "https://www.gstatic.com/webp/gallery3/1.png"
                }],
                "type": "conversation"
            }
        }
    },
    "destination": [{
        "psid":["1207588322640336"]
    }]
}
{
    "appid": "",
    "notifyurl": "",
    "deliverychannel": "fb",
    "channels": {
        "OTT-Messaging": {
            "fb": {
                "attachment": {
                    "type": "image",
                    "payload": {
                        "url": "https://encrypted-tbn2.gstatic.com/images?q=tbn:ANd9GcR5LtraajVrX9XqOtN9nhyFG9i9aJhhKcFG4LLZuw34ognS6zXQWkwOnILR"
                    }
                }
            }
        }
    },
  
    "destination": [{
      
        "psid":["1207588322640336"]
    }]
}
{
    "appid": "",
    "notifyurl": "",
    "deliverychannel": "fb",
    "channels": {
        "OTT-Messaging": {
            "fb": {
                "attachment": {
                    "type": "audio",
                    "payload": {
                        "url": "http://www.stephaniequinn.com/Music/Pachelbel%20-%20Canon%20in%20D%20Major.mp3"
                    }
                }
            }
        }
    },
    "destination": [{
        "psid":["1207588322640336"]
    }]
}
{
    "appid": "",
    "notifyurl": "",
    "deliverychannel": "fb",
    "channels": {
        "OTT-Messaging": {
            "fb": {
                "attachment": {
                    "type": "video",
                    "payload": {
                        "url": "http://www.sample-videos.com/video/mp4/720/big_buck_bunny_720p_1mb.mp4"
                    }
                }
            }
        }
    },
    "destination": [{
        "psid":["1207588322640336"]
    }]
}
{
    "appid": "",
    "notifyurl": "",
    "deliverychannel": "fb",
    "channels": {
        "OTT-Messaging": {
            "fb": {
                "attachment": {
                    "type": "file",
                    "payload": {
                        "url": "http://www.pdf995.com/samples/pdf.pdf"
                    }
                }
            }
        }
    },
    "destination": [{
        "psid":["1207588322640336"]
    }]
}
{
    "appid": "",
    "notifyurl": "",
    "deliverychannel": "fb",
    "channels": {
        "OTT-Messaging": {
            "fb": {
                "attachment": {
                    "type": "template",
                    "payload": {
                        "template_type": "generic",
                        "elements": [{
                            "title": "Classic White T-Shirt",
                            "image_url": "http://petersapparel.parseapp.com/img/item100-thumb.png",
                            "subtitle": "Soft white cotton t-shirt is back in style",
                            "buttons": [{
                                "type": "web_url",
                                "url": "https://petersapparel.parseapp.com/view_item?item_id=100",
                                "title": "View Item"
                            }, {
                                "type": "web_url",
                                "url": "https://petersapparel.parseapp.com/buy_item?item_id=100",
                                "title": "Buy Item"
                            }, {
                                "type": "postback",
                                "title": "Bookmark Item",
                                "payload": "check"
                            }]
                        }, 
                            {
                            "title": "Giordano 60058 Black/Orange Analog Watch - For Men",
                            "image_url": "http://img6a.flixcart.com/image/watch/g/q/z/60058-black-orange-giordano-400x400-imae7c8rhnp4rfze.jpeg",
                            "subtitle": "Watch Watch",
                            "buttons": [{
                                "type": "web_url",
                                "url": "http://www.flipkart.com/giordano-60058-black-orange-analog-watch-men/p/itmdw4v6gkgejetj?pid=WATDW4V5GYEYQGQZ&al=rWnbPKcgb3ESJptH0q72XsldugMWZuE7Phn6Yd2VMSLMQz8fzEH13Ce0tGaT7ePiWmFmBeJJs7Q%3D&offer=nb%3Amp%3A0405c80713&ref=L%3A-7770517350658453810&srno=b_1",
                                "title": "View Item"
                            }, {
                                "type": "web_url",
                                "url": "https://petersapparel.parseapp.com/buy_item?item_id=101",
                                "title": "Buy Item"
                            }, {
                                "type": "postback",
                                "title": "Bookmark Item",
                                "payload": "USER_DEFINED_PAYLOAD_FOR_ITEM101"
                            }]
                        }]
                    }
                }

            }
        }
    },
    "destination": [{
        
      "psid": ["1207588322640336"]
    }]
}
{
    "appid": "",
    "notifyurl": "",
    "deliverychannel": "fb",
    "channels": {
        "OTT-Messaging": {
            "fb": {
                "attachment": {
                    "type": "template",
                    "payload": {
                        "template_type": "button",
                        "text": "Do you want to Play football",
                        "buttons": [
                          {
                            "type": "web_url",
                            "url": "https://www.google.co.in/maps/@17.4495157,78.4000172,16z?hl=en",
                            "title": "Show location"
                        }, {
                            "type": "postback",
                            "title": "Start Chatting",
                            "payload": "1232"
                        }, {
                            "type": "phone_number",
                            "title": "Call Representative",
                            "payload": "+917767984884"
                        }]
                    }
                }

            }
        }
    },
    "destination": [{
        "psid":["1207588322640336"]
    }]
}
{
    "appid": "",
    "notifyurl": "",
    "deliverychannel": "fb",
    "channels": {
        "OTT-Messaging": {
            "fb": {

                "attachment": {
                    "type": "template",
                    "payload": {
                        "template_type": "receipt",
                        "recipient_name": "Stephane Crozatier",
                        "order_number": "1234444415678902",
                        "currency": "USD",
                        "payment_method": "Visa 2345",
                        "order_url": "http://petersapparel.parseapp.com/order?order_id=123456",
                        "timestamp": "1428444852",
                        "elements": [ {
                            "title": "Classic White T-Shirt",
                            "subtitle": "100% Soft and Luxurious Cotton",
                            "quantity": 2,
                            "price": 50,
                            "currency": "USD",
                            "image_url": "http://petersapparel.parseapp.com/img/whiteshirt.png"
                        }, {
                            "title": "Classic Gray T-Shirt",
                            "subtitle": "100% Soft and Luxurious Cotton",
                            "quantity": 1,
                            "price": 25,
                            "currency": "USD",
                            "image_url": "http://petersapparel.parseapp.com/img/grayshirt.png"
                        }],
                        "address": {
                            "street_1": "1 Hacker Way",
                            "street_2": "",
                            "city": "Menlo Park",
                            "postal_code": "94025",
                            "state": "CA",
                            "country": "US"
                        },
                        "summary": {
                            "subtotal": 75.00,
                            "shipping_cost": 4.95,
                            "total_tax": 6.19,
                            "total_cost": 56.14
                        },
                        "adjustments": [{
                            "name": "New Customer Discount",
                            "amount": 20
                        }, {
                            "name": "$10 Off Coupon",
                            "amount": 10
                        }]
                    }
                }

            }
        }
    },
    "destination": [{
        "psid":["1207588322640336"]

    }]
}
{
    "appid": "",
    "notifyurl": "",
    "deliverychannel": "fb",
    "channels": {
        "OTT-Messaging": {
            "fb": {
                "attachment": {
                    "type": "template",
                    "payload": {
                        "template_type": "airline_itinerary",
                        "intro_message": "Here's your flight itinerary.",
                        "locale": "en_US",
                        "pnr_number": "ABCDEF",
                        "passenger_info": [{
                            "name": "Farbound Smith Jr",
                            "ticket_number": "0741234567890",
                            "passenger_id": "p001"
                        }, {
                            "name": "Nick Jones",
                            "ticket_number": "0741234567891",
                            "passenger_id": "p002"
                        }],
                        "flight_info": [{
                            "connection_id": "c001",
                            "segment_id": "s001",
                            "flight_number": "KL9123",
                            "aircraft_type": "Boeing 737",
                            "departure_airport": {
                                "airport_code": "SFO",
                                "city": "San Francisco",
                                "terminal": "T4",
                                "gate": "G8"
                            },
                            "arrival_airport": {
                                "airport_code": "SLC",
                                "city": "Salt Lake City",
                                "terminal": "T4",
                                "gate": "G8"
                            },
                            "flight_schedule": {
                                "departure_time": "2016-01-02T19:45",
                                "arrival_time": "2016-01-02T21:20"
                            },
                            "travel_class": "business"
                        }, {
                            "connection_id": "c002",
                            "segment_id": "s002",
                            "flight_number": "KL321",
                            "aircraft_type": "Boeing 747-200",
                            "travel_class": "business",
                            "departure_airport": {
                                "airport_code": "SLC",
                                "city": "Salt Lake City",
                                "terminal": "T1",
                                "gate": "G33"
                            },
                            "arrival_airport": {
                                "airport_code": "AMS",
                                "city": "Amsterdam",
                                "terminal": "T1",
                                "gate": "G33"
                            },
                            "flight_schedule": {
                                "departure_time": "2016-01-02T22:45",
                                "arrival_time": "2016-01-03T17:20"
                            }
                        }],
                        "passenger_segment_info": [{
                            "segment_id": "s001",
                            "passenger_id": "p001",
                            "seat": "12A",
                            "seat_type": "Business",
                            "product_info": [{
                                "title": "Lounge",
                                "value": "Complimentary lounge access"
                            }, {
                                "title": "Baggage",
                                "value": "1 extra bag 50lbs"
                            }]
                        }, {
                            "segment_id": "s001",
                            "passenger_id": "p002",
                            "seat": "12B",
                            "seat_type": "Business",
                            "product_info": [{
                                "title": "Lounge",
                                "value": "Complimentary lounge access"
                            }, {
                                "title": "Baggage",
                                "value": "1 extra bag 50lbs"
                            }]
                        }, {
                            "segment_id": "s002",
                            "passenger_id": "p001",
                            "seat": "73A",
                            "seat_type": "World Business",
                            "product_info": [{
                                "title": "Lounge",
                                "value": "Complimentary lounge access"
                            }, {
                                "title": "Baggage",
                                "value": "1 extra bag 50lbs"
                            }]
                        }, {
                            "segment_id": "s002",
                            "passenger_id": "p002",
                            "seat": "73B",
                            "seat_type": "World Business",
                            "product_info": [{
                                "title": "Lounge",
                                "value": "Complimentary lounge access"
                            }, {
                                "title": "Baggage",
                                "value": "1 extra bag 50lbs"
                            }]
                        }],
                        "price_info": [{
                            "title": "Fuel surcharge",
                            "amount": "1597",
                            "currency": "USD"
                        }],
                        "base_price": "12206",
                        "tax": "200",
                        "total_price": "14003",
                        "currency": "USD"
                    }
                }
            }
        }
    },
    "destination": [{
        "psid":["1207588322640336"]
    }]
}
{
    "appid": "",
    "notifyurl": "",
    "deliverychannel": "fb",
    "channels": {
        "OTT-Messaging": {
            "fb": {
                "attachment": {
                    "type": "template",
                    "payload": {
                        "template_type": "airline_checkin",
                        "intro_message": "Check-in is available now.",
                        "locale": "en_US",
                        "pnr_number": "ABCDEF",
                        "flight_info": [{
                            "flight_number": "f001",
                            "departure_airport": {
                                "airport_code": "SFO",
                                "city": "San Francisco",
                                "terminal": "T4",
                                "gate": "G8"
                            },
                            "arrival_airport": {
                                "airport_code": "SEA",
                                "city": "Seattle",
                                "terminal": "T4",
                                "gate": "G8"
                            },
                            "flight_schedule": {
                                "boarding_time": "2016-01-05T15:05",
                                "departure_time": "2016-01-05T15:45",
                                "arrival_time": "2016-01-05T17:30"
                            }
                        }],
                        "checkin_url": "https:\/\/www.airline.com\/check-in"
                    }
                }
            }
        }
    },
    "destination": [{
        "psid":["1207588322640336"]
    }]
}
{
    "appid": "",
    "notifyurl": "",
    "deliverychannel": "fb",
    "channels": {
        "OTT-Messaging": {
            "fb": {
                "attachment": {
                    "type": "template",
                    "payload": {
                        "template_type": "airline_boardingpass",
                        "intro_message": "You are checked in.",
                        "locale": "en_US",
                        "boarding_pass": [{
                            "passenger_name": "SMITH\/NICOLAS",
                            "pnr_number": "CG4X7U",
                            "travel_class": "business",
                            "seat": "74J",
                            "auxiliary_fields": [{
                                "label": "Terminal",
                                "value": "T1"
                            }, {
                                "label": "Departure",
                                "value": "30OCT 19:05"
                            }],
                            "secondary_fields": [{
                                "label": "Boarding",
                                "value": "18:30"
                            }, {
                                "label": "Gate",
                                "value": "D57"
                            }, {
                                "label": "Seat",
                                "value": "74J"
                            }, {
                                "label": "Sec.Nr.",
                                "value": "003"
                            }],
                            "logo_image_url": "https:\/\/www.example.com\/en\/logo.png",
                            "header_image_url": "https:\/\/www.example.com\/en\/fb\/header.png",
                            "qr_code": "M1SMITH\/NICOLAS  CG4X7U nawouehgawgnapwi3jfa0wfh",
                            "above_bar_code_image_url": "https:\/\/www.example.com\/en\/PLAT.png",
                            "flight_info": {
                                "flight_number": "KL0642",
                                "departure_airport": {
                                    "airport_code": "JFK",
                                    "city": "New York",
                                    "terminal": "T1",
                                    "gate": "D57"
                                },
                                "arrival_airport": {
                                    "airport_code": "AMS",
                                    "city": "Amsterdam"
                                },
                                "flight_schedule": {
                                    "departure_time": "2016-01-02T19:05",
                                    "arrival_time": "2016-01-05T17:30"
                                }
                            }
                        }, {
                            "passenger_name": "JONES\/FARBOUND",
                            "pnr_number": "CG4X7U",
                            "travel_class": "business",
                            "seat": "74K",
                            "auxiliary_fields": [{
                                "label": "Terminal",
                                "value": "T1"
                            }, {
                                "label": "Departure",
                                "value": "30OCT 19:05"
                            }],
                            "secondary_fields": [{
                                "label": "Boarding",
                                "value": "18:30"
                            }, {
                                "label": "Gate",
                                "value": "D57"
                            }, {
                                "label": "Seat",
                                "value": "74K"
                            }, {
                                "label": "Sec.Nr.",
                                "value": "004"
                            }],
                            "logo_image_url": "https:\/\/www.example.com\/en\/logo.png",
                            "header_image_url": "https:\/\/www.example.com\/en\/fb\/header.png",
                            "qr_code": "M1JONES\/FARBOUND  CG4X7U nawouehgawgnapwi3jfa0wfh",
                            "above_bar_code_image_url": "https:\/\/www.example.com\/en\/PLAT.png",
                            "flight_info": {
                                "flight_number": "KL0642",
                                "departure_airport": {
                                    "airport_code": "JFK",
                                    "city": "New York",
                                    "terminal": "T1",
                                    "gate": "D57"
                                },
                                "arrival_airport": {
                                    "airport_code": "AMS",
                                    "city": "Amsterdam"
                                },
                                "flight_schedule": {
                                    "departure_time": "2016-01-02T19:05",
                                    "arrival_time": "2016-01-05T17:30"
                                }
                            }
                        }]
                    }
                }
            }
        }
    },
    "destination": [{
        "psid":["1207588322640336"]
    }]
}
{
    "appid": "",
    "notifyurl": "",
    "deliverychannel": "fb",
    "channels": {
        "OTT-Messaging": {
            "fb": {

                "attachment": {
                    "type": "template",
                    "payload": {
                        "template_type": "airline_update",
                        "intro_message": "Your flight is delayed",
                        "update_type": "delay",
                        "locale": "en_US",
                        "pnr_number": "CF23G2",
                        "update_flight_info": {
                            "flight_number": "KL123",
                            "departure_airport": {
                                "airport_code": "SFO",
                                "city": "San Francisco",
                                "terminal": "T4",
                                "gate": "G8"
                            },
                            "arrival_airport": {
                                "airport_code": "AMS",
                                "city": "Amsterdam",
                                "terminal": "T4",
                                "gate": "G8"
                            },
                            "flight_schedule": {
                                "boarding_time": "2015-12-26T10:30",
                                "departure_time": "2015-12-26T11:30",
                                "arrival_time": "2015-12-27T07:30"
                            }
                        }
                    }
                }
            }
        }
    },
    "destination": [{
        "psid":["1207588322640336"]
    }]
}
{
    "deliverychannel": "twitter",
    "channels": {
        "OTT-Messaging": {
            "twitter": {
                "text": "First Twitter Message"
            }
        }
    },
    "destination": [{
        "customerid": [
            "54"
        ]
    }]
}
{
    "deliverychannel": "wechat",
    "channels": {
        "OTT-Messaging": {
            "wechat": {
                "attachment": {
                    "type": "voice",
                    "media_id": "EUKdxzrZuAdTLvZ7Vyzdv36VwmzTmJe_FwZE5ObkzeZlOHVlVR_CxctmQ3A9vmw0"
                }

            }
        }
    },
    "destination": [{
        "wechat_user_id": ["ocTeNt9KP1IIJ44WdeiqF7R_OeCw"]
    }]
}
{
    "deliverychannel": "wechat",
    "channels": {
      "smartlinks":[
        {
            "linkid": 5,
            "validity": 30
        }
      ],
        "OTT-Messaging": {
            "wechat": {
              "text":"Sending first WeChat message with Smartlink using IMIconnect. Click the link to get surprise gift {{link_5}}"
            }
        }
    },
    "destination": [{
        "wechat_user_id": ["ocTeNt9KP1IIJ44WdeiqF7R_OeCw"]
    }]
}

{
    "deliverychannel": "wechat",
    "message": {
        "template": "3"
    },
    "channels": {
        "OTT-Messaging": {
            "wechat": {}
        }
    },
    "destination": [{
        "wechat_user_id": ["ocTeNt9KP1IIJ44WdeiqF7R_OeCw"]
    }]
}
{
  "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": [
    {
      "code": "1001",
      "description": "Queued",
      "transid": "f9793c83-f0b7-4200-99d9-20111c507baf",
      "correlationid": "cid"
    }
  ]
}  
Suggest Edits

Unified API

This single API provides a multitude of functionality for multi-channel outbound messaging

 
posthttps://api.imiconnect.io/resources/v1/messaging
 

Request

The messaging request is specified as follows:

None.

Request Headers

The following table describes the request headers:

Request Header
Description

key

Service Key

content-type

application/json

The following table describes the elements in the request body:

Parameter
Type
Mandatory
Description

deliverychannel

String

Yes

Specifies the channel to send a message. (sms/voice/push/rt/fb/twitter/wechat).

destination

JSONArray

Yes

The destination parameter is a sub-parameter array of strings. This allows multiple destinations.

channels

JSONArray

Yes

The channel parameter encompasses sub-parameters.

message

JSONObject

No

This parameter is used when the message consisting of a predefined template.

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

A URL that receives notifications. This overrides the service's Notify URL.

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.

Response Body

The format of the response body is as follows:

{
  "response": [
    {
      "code": "1001",
      "description": "Queued",
      "transid": "f9793c83-f0b7-4200-99d9-20111c507baf",
      "correlationid": "cid"
    }
  ]
}  

Response / return codes

This API may return the following response codes:

Response Code
Message
Description

1001

Queued

Returned when the request is accepted by IMIconnect.

7000

Invalid JSON

Returned when an invalid JSON request is sent.

7001

Authentication failed

Returned when an invalid service key or profile key is provided in the request.

7002

Service key missing

Returned when the parameter key is missing in the message request.

7003

Mandatory parameters missing

Returned when the mandatory parameters configured in custom event are missing.

7004

Invalid parameters

Returned when the parameters are invalid.

7006

Internal error occurred

Returned when an internal error occurs.

7007

Service inactive

Returned when the service is in inactive state.

7009

Max number of destinations

Returned when an API request exceeds the limit (1000) to send messages using messaging API.

Parameters

The section below details all the parameters within the API request.

correlationid

A client-side identifier chosen by the Service Provider to correlate requests and their subsequent responses. The correlationid can be up to 50 bytes long.

{  
   "correlationid":"<Unique transaction ID from the client end up to 50 bytes.>"
}

notifyurl

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.

More information of receipts can be found here - http://docs.imiconnect.com/docs/delivery-and-read-receipt-notifications.

{
   "deliveryInfoNotification":{
      "correlationid":"32607da6-8b72-4b71-990d-15d05765c7e6",
      "transid":"2137c260-dae8-4ffa-9ca8-3f5d8a4cab8e",
      "callbackData":"some-use-ful-data",
      "deliveryInfo":{
         "destination":"2105",
         "deliveryStatus":"Delivered",
         "deliveryChannel":"SMS"
      }
   }
}
{  
   "notifyurl":"<Notifications will be sent to the URL specified here>"
}

callbackData

An identifier or data that will be sent alongside notifications to the URL specified in notifyurl.

priority

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.

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.

message

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.

Using parameters

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.

Message length is limited as per channel used. The sizes are:

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

destination

The destination parameter can be a string array of up to 1,000 entries.

Messages can be sent to single or multiple recipients in a single request.

Name
Description

customerid

A customerid is the Client specific unique alphanumerical ID for distinguishing customers. The IMIconnect platform uses this customerid to reference a Customer Profile which may contains one or more customer contact details.

The IMIconnect platform will intelligently match the appropriate communication detail within the context of the current communication method.

msisdn

A msisdn is the Mobile Station International Subscriber Directory Number.

The msisdn is the subscriber number in international format that starts with the country code and continues with the subscribe number (with the leading zero omitted). For instance the UK number 01234567890 becomes 441234567890.

email

Destination specific ID.

android_pushid

Specifies the Android push ID.

ios_pushid

Specifies the iOS push ID.

chrome_pushid

Specifies the Chrome push ID.

firefox_pushid

Specifies the Firefox push ID and key. The format is pushid@key.

safari_pushid

Specifies the Safari push ID.

psid

Destination specific ID.

twitterid

Destination specific ID.

wechat_user_id

Destination specific ID.

correlationid

A unique transaction ID used by a Client to match requests with responses.

Note: This value will override the correlationid in the request body.

deliverychannel

The deliverychannel value determines the channel to use for delivering messages.

The deliverychannel value may be one of the following:

Channel
Description

sms

Short Messaging Service.

Messages are limited to 1024 bytes.

voice

Voice services.

push

Push messaging service

appmessaging

Real Time channel that sends messages to enabled mobile apps to provide App-Messaging.

Supports rich multimedia messages with text and optional multimedia items.

fb

Facebook

twitter

Twitter

Messages are limited to 140 bytes.

wechat

WeChat

channels

The channels parameter block configures channel communication parameters and will overrides the service's default values and the parameters in the base request.

Click the respective channel links to go to channels API details.

Channel
Subchannels

None

None

  • Android
  • iOS
  • Windows
  • Web
    • Chrome
    • Firefox
    • Safari
  • fb
  • twitter
  • wa
  • wechat

smartlinks

Smartlinks are supported in the following channels:

  • SMS
  • RT
  • OTT-Messaging channels

smartlinks

An array that contains the parameters of Smartlink. This is an optional. 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 in Messaging. The link id gets generated when a Smartlink is created in IMIconnect.

validity

Number

No

Specifies the time in minutes after which the link will expire.

Request Body

{
  "correlationid":"<Unique transaction ID from the client end>", //optional
  "notifyurl":"<Notifications will be sent to the URL specified here>", //optional
  "callbackData":"<Identifier sent alongside notifications to the notifyurl>", //optional
  "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.>", //optional
	"priority": "<Accepts numbers 1-low, 2-medium, and 3-high>", //optional
  "deliverychannel":"<Channel to use for delivery: (sms/voice/push/rt/fb/twitter/wa/wechat>", //Mandatory 
  "message":{//optional
    "template":"<Message template ID.>",
    "parameters":{
      "parameter1":"<value>",
      "parameter2":"<value>",
      "parameter3":"<value>"
    }
  },
   "channels":{ //Mandatory
      "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>"
        }
      ],
      "sms":{
        "type":"<Message type 1– Text, 2- Flash, 3– Binary, 4– Unicode>",
        "text":"<Channel specific message text>",
        "body":"<Hexadecimal content for binary type message>",
        "media-path":"<Media path which will be appended to SMS text>",
        "senderid":"<Predefined Sender ID for this message>"
      },
      "voice":{ //Either callflowid or promptid must be passed in the request. If you pass both the parameters, promptid takes the priority.
        "callflowid":"<Call Flow ID (Created in Call Flow Builder).>",
        "promptid":"<id of the uploaded media file (Id is displayed in IMIconnect UI after uploading the file).>",
        "cli":"<Predefined Caller Line Identity to initiate the call.>"
      },
      "appmessaging": {
            "message": {
                "text": "RTM_message",
                "attachment": {
                    "file": "<URL of resource, e.g. http://ip/image.jpg>",
                    "contentType": "image",
                    "size": "10"
                }
            },
            "notification": {
                "web_extras": {
                    "collapse_key": "web_col_key",
                    "action": "web_col_key",
                    "url": "<Valid http URL>"
                },
                "title": "notification_title",
                "text": "notification_text",
                "windows_extras": {
                    "logo": "<URL of resource, e.g. http://ip/image.jpg>",
                    "sound": "wind_not_sound",
                    "image": "<URL of resource, e.g. http://ip/image.jpg>",
                    "badge": "wnd_badge",
                    "notificationaction": {
                        "action": "OPEN_URL",
                        "value": "<Valid HTTP URL>"
                    }
                },
                "interactive": {
                    "category": "DOUBLE_YES_NO",
                    "pushref": "pu_ref",
                    "actions": [{
                            "action": "OPEN_APP",
                            "identifier": "YES",
                            "pos": 1
                        }, {
                            "action": "OPEN_APP",
                            "identifier": "NO",
                            "pos": 2
                        }
                    ]
      },
      "push":{
        "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 of the button for safari browsers only>",
          "platorm_types" : ["chrome", "safari", "firefox"],//Specifies the browsers to which the message is sent.
          "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>"
            }
          ]
        },
        "OTT-Messaging":{
          "fb":{
            "text":"<Channel specific message text>",    
            "attachment": {
                "type": "<type of attachment: image/template>",
                "payload": { 
                    "template_type": "<type of template: generic/buttons/receipt>",
                    "elements": [{
                        "title": "<bubble title>",
                        "image_url": "<image url that opens when bubble is tapped>",
                            "subtitle": "<subtitle for a bubble>",
                            "buttons": [{
                               "type": "<options for button: web_url/postback>",
                               "url": "<Applicable when button type is web url. Specifies the url that opens in a browser when button is tapped>",
                               "title": "<url title>",
                               "payload": "<Applicable when button type is postback. A user defined payload  that is used in rules>"
                                }]
                            }

                        ]
                    }
                }       
            },
          "twitter":{
            "text":"<Channel specific message text>"
          },
          "wechat": {//text or attachment must be provided. If you provide both, only text is delivered.
              "text": "<Channel specific message text>",
              "attachment": {//Use this object if you have uploaded media without using IMIconnect. 
              "type": "<Supported file types as attachment image/video/>",
              "media_id": "<Media id received from WeChat for the uploaded file>"
              }
           }
        }
      },
      "destination":[ //Mandatory
        {
          "customerid/msisdn/email/android_pushid/ios_pushid/chrome_pushid/safari_pushid/psid/twitterid/wechat_user_id":[
            "<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.>"
        },
        {
          "customerid/msisdn/email/android_pushid/ios_pushid/chrome_pushid/safari_pushid/psid/twitterid/wechat_user_id":[
            "<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.>"
        }
      ]
    }
  
}
{  
   "correlationid":"<Unique transaction ID from the client end>", //Optional
   "notifyurl":"<Notifications will be sent to the URL specified here>", //Optional
   "callbackData":"<Identifier sent alongside notifications to the notifyurl>", //Optional
   "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>", //Optional
   "priority":"<Accepts numbers 1-low, 2-medium, and 3-high>", //Optional
   "deliverychannel":"sms", //Mandatory
   "message":{  //Optional
      "template":"<Message template ID.>",
      "parameters":{  
         "parameter1":"<value>",
         "parameter2":"<value>",
         "parameter3":"<value>"
         }
      },
      "channels":{  //Mandatory
         "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>"
        }
      ],
         "sms":{  
            "type":"<Message type 1– Text, 2- Flash, 3– Binary, 4– Unicode>",
            "text":"<Channel specific message text>",
            "body":"<Hexadecimal content for binary type message>",
            "media-path":"<Media path which will be appended to SMS text>",
            "senderid":"<Predefined Sender ID for this message>"
         }
      },
      "destination":[  //Mandatory
         {  
            "msisdn/customerid":[  
               "<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.>"
         },
         {  
            "msisdn/customerid":[  
               "<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.>" //Optional
         }
      ]
   
}
{  
   "correlationid":"<Unique transaction ID from the client end>", //Optional
   "notifyurl":"<Notifications will be sent to the URL specified here>", //Optional
   "callbackData":"<Identifier sent alongside notifications to the notifyurl>", //Optional
   "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>", //Optional
   "priority":"<Accepts numbers 1-low, 2-medium, and 3-high>", //Optional
   "deliverychannel":"voice", //Mandatory
   "message":{  //Optional
      "template":"<Message template ID.>",
      "parameters":{  
         "parameter1":"<value>",
         "parameter2":"<value>",
         "parameter3":"<value>"
          }
      },
      "channels":{  //Mandatory
         "voice":{ //Either callflowid or promptid must be passed in the request. If you pass both the parameters, promptid takes the priority.
        "callflowid":"<Call Flow ID (Created in Call Flow Builder).>",
        "promptid":"<id of the uploaded media file (Id is displayed in IMIconnect UI after uploading the file).>",
        "cli":"<Predefined Caller Line Identity to initiate the call.>"
      }
      },
      "destination":[  //Mandatory
         {  
            "msisdn/customerid":[  
               "<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.>"
         },
         {  
            "msisdn/customerid":[  
               "<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.>" //Optional
         }
      ]
   
}
{  
   "correlationid":"<Unique transaction ID from the client end>", //Optional
   "notifyurl":"<Notifications will be sent to the URL specified here>", //Optional
   "callbackData":"<Identifier sent alongside notifications to the notifyurl>", //Optional
   "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>", //Optional
   "priority":"<Accepts numbers 1-low, 2-medium, and 3-high>", //Optional
   "deliverychannel":"rt", //Mandatory
   "message":{  //Optional
      "template":"<Message template ID.>",
      "parameters":{  
         "parameter1":"<value>",
         "parameter2":"<value>",
         "parameter3":"<value>"
         }
      },
      "channels":{  //Mandatory
         "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>"
        }
      ],
         "appmessaging":{  
            "senderid":"<App Messaging sender ID>",
            "extras":{  
               "notificationaction":{
                     "action":"OPEN_URL",
                     "value":"www.google.com"
                        },
               "customtags":{  
                  "key1":"object1",
                  "key2":{  
                     "object2":"val"
                  },
                  "key3":[  
                     "object3",
                     "object4"
                  ]
               }
            },
            "text":"<Channel specific message text>",
            "priority":"<A value from 1 to 5, where 5 is the highest.>",
            "attachments":[
                {
                   "contentType":"<MIME content type, eg. image>",
                   "file":"<URL of resource, e.g. http://ip/image.jpg>",
                   "preview":"<A base64 string of a preview image in JPEG format for video>",
                   "size":"<Size of file in bytes>",
                   "duration":"<Length of audio or video in seconds.>",
                   "latitude":"<Latitude location>",
                   "longitude":"<Longitude location>"
                }
            ],
            "interactive":{  
               "messageref":"<Message reference, for use with as a trigger for rules.>",
               "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":"<Depends on the action>"
                  },
                  {  
                     "pos":2,
                     "action":"<Actions depend on the category>",
                     "value":"<Depends on the action>"
                  }
               ]
            }
         }
      },
      "destination":[  //Mandatory
         {  
            "msisdn/customerid":[  
               "<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.>"
         },
         {  
            "customerid":[  
               "<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.>"
         }
      ]
   
}
{
    "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": {
            "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 of the button for safari browsers only>",
                "platorm_types": ["chrome", "safari", "firefox"],
                "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>"
                }]
            }
        }
    },
    "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.>"
    }, {
        "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.>"
    }]
}
{  
   "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":"fb/twitter/wa/wechat",
   "message":{  
      "template":"<Message template ID.>",
      "parameters":{  
         "parameter1":"<value>",
         "parameter2":"<value>",
         "parameter3":"<value>"
          }
      },
      "channels":{
         "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>"
        }
      ],
        "OTT-Messaging":{
          "fb":{
                "attachment": {
                    "type": "<type of attachment: image/template>",
                    "payload": { 
                        "template_type": "<type of template: generic/buttons/receipt>",
                        "elements": [{
                             "title": "<bubble title>",
                             "image_url": "<image url that opens when bubble is tapped>",
                             "subtitle": "<subtitle for a bubble>",
                             "buttons": [{
                                 "type": "<options for button: web_url/postback>",
                                 "url": "<Applicable when button type is web url. Specifies the url that opens in a browser when button is tapped>",
                                 "title": "<url title>",
                                 "payload": "<Applicable when type is postback. A user defined payload that  is used in rules>"
                                }]
                            }

                        ]
                    }
                }       
            },
            "twitter":{
               "text":"<Channel specific message text>"
            },
            "wa":{  
               "text":"<Channel specific message text>"
            },
            "wechat": {//text or attachment must be provided. If you provide both, only text is delivered.
               "text": "<Channel specific message text>",
               "attachment": {//Use this object if you have uploaded media without using IMIconnect. 
               "type": "<Supported file types as attachment image/video/>",
               "media_id": "<Media id received from WeChat for the uploaded file>"
              }
           }
         }
      },
      "destination":[  
         {  
            "customerid/psid/twitterid/wechat_user_id":[  
               "<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.>"
         },
         {  
            "customerid/psid/twitterid/wechat_user_id":[  
               "<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.>"
         }
      ]
   
}
{  
    "callbackData":"<An identifier that will be returned via the notifyurl.>"
}
{

    "priority": "1",
    "deliverychannel": "sms",
    "channels": {
        "sms": {
            "text": "test",
            "type": "1"
        }
    },
    "destination": [{
        "msisdn": ["918519909999"]
    }]

}
{
   "expiry":"2015-04-12T13:00:19.456Z " <//UTC message expiry time> 
}
{

   "message":{  
      "template":"<Template ID>",
      "parameters":{  
         "parameter1":"<value>",
         "parameter2":"<value>",
         "parameter3":"<value>"
      },
   }
...
}
{
  "destination":[
    {
      "customerid/msisdn/email/psid/android_pushid/ios_pushid/chrome_pushid/firefox_pushid/safari_pushid/twitterid/wechat_user_id":[
        "<value1>",
        "<value2>"
      ],
      "correlationid":"<Will override correlationid given in request body>"
    },
    {
      "customerid/msisdn/email/psid/android_pushid/ios_pushid/chrome_pushid/firefox_pushid/safari_pushid/twitterid/wechat_user_id":[
        "<value1>",
        "<value2>"
      ],
      "correlationid":"<Will override correlationid given in request body>"
    }
  ]
}
{
  "deliverychannel":"<sms/voice/push/rt/fb/twitter/wa/wechat>"
}
{
  "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>"
        }
      ]
}
 

The Event API is a single API that allows third party/external applications to make event requests using a RESTful API over HTTPS to the IMIconnect platform.

External application can raise one or more events in a single request. Each event can be attached with a set of parameters representing event specific information. These parameters will be passed along as context parameters to the actions defined in the rules on these events.

Clients can create custom events and configure rules that are executed when the event API request is received on the IMIconnect platform. Events are defined in the services section by defining parameter blocks that consist of variable names and types. These will then be passed when the event is invoked.

A Service Key must be passed with every API request.

Prerequisites:

  • A Service Key. The Service Key is obtained by creating a service.
  • An event associated with the Service.
  • At least one Rule associated with the Event.
  • Properly defined actions for the Rule in order to complete the expected flow.

API parameters

For data privacy and security reasons, the REST API is served over encrypted HTTPS. Standard HTTP is not supported.

Parameter
Mandatory
Use
Description

key

Yes

Passed in the header.

The service key authenticates event API requests and must be passed with every request.

events

Yes

Passed in the request body.

An array containing a list of events.

notifyurl

No

Passed in the request body.

A notification is sent to the specified notifyurl after an event is executed.

expiry

No

Passed in the request body.

Expiry time of event in UTC format.

Response / Error Codes

Code
Message
Description

1002

Queued

Returned when the request is accepted by IMIconnect.

7000

Invalid JSON

Returned when an invalid JSON request is sent.

7001

Authentication failed

Returned when an invalid service key or profile key is provided in the request.

7003

Mandatory parameters missing

Returns when any mandatory parameter is missing in request body.

7004

Invalid parameters/values

Returns when any invalid value is given for any parameter in request body.

7005

Internal error occurred

Returned when an internal error occurs.

7025

Mandatory custom parameters missing

Returns when any mandatory custom event parameter is missing, where these custom parameters are created in custom event creation screen.

Suggest Edits

Custom Event v1

This API allows third party/external applications to make event requests using a RESTful API over HTTPS to the IMIconnect platform.

 
posthttps://api.imiconnect.io/resources/v1/events/externalevent/
 

Prerequisites

Following are the prerequisites to use this API.

Service Key

A service must be created in IMIconnect to get a service key. Click here to create a service.

Event

Create an event in a service.

Rule

Create a rule within the event.

Actions

Create actions within the rule.

Request

The event request is specified as follows:

URI

https://api.imiconnect.com/resources/v1/events/externalevent/

 
Note: If your IMIconnect web access URL is on a .io TLD, then you should use the API end point with .io. For example, if your domain is mycompany.imiconnect.com then your API base URL will be api.imiconnect.com. But, if your domain is mycompany.imiconnect.io then your API base URL will be api.imiconnect.io.

Method

POST

Request Headers

The following table describes the request headers:

Request Header
Description

key

Service Key

content-type

application/json

Request Body

The following table describes the elements in the request body:

Parameter
Type
Mandatory
Description

expiry

String

No

Expiry time is in UTC format, after which no action is taken. For example,

{
"expiry":"2015-04-12T18:51:19"//expiry time in utc format
}

notifyurl

String

No

Specifies a URL that receives notifications. This URL overrides the service's Notify URL. For example,

{
"notifyurl":"<Notification URL>"
}

events

Array of Strings

Yes

Specifies the events in an array. The parameters are:

  • evtid: Mandatory {String} - Specifies the event id that is generated by IMIconnect.
  • correlationid: Optional {String} - Specifies a unique transaction ID up to 50 bytes used by service providers to match requests with responses.
  • parameters: Optional {JSONObject} - Specifies the parameters block that may contain multiple name/value pairs if required to pass additional information to the event/trigger handler.

For example,

{
"events":[
    {
        "evtid":"<Event ID>",
        "correlationid":"<Correlation ID>",
        "parameters":
         {
            "param1":"value1",
            "param2":"value2",
             ...
         }
    }
  ]    

}

If a mandatory parameter is missing, then the API will execute with default values. If the default values are not defined then the API request will be rejected.
If an optional parameter is missing, then the API will execute with default values. The API request is accepted even if the default values are not defined.

Response / return codes

This API may return the following response codes:

Response Code
Message
Description

1002

Queued

Returned when the request is accepted by IMIconnect.

7000

Invalid JSON

Returned when an invalid JSON request is sent.

7001

Authentication failed

Returned when an invalid service key or profile key is provided in the request.

7004

Invalid parameters/values

Returns when any invalid value is given for any parameter in request body.

7005

Internal error occurred

Returned when there is an issue with IMIconnect.

7020

You have reached maximum transaction limit

Returned when you have reached the transaction limit.

7025

Mandatory custom parameters missing

Returns when any mandatory custom event parameter is missing, where these custom parameters are created in custom event creation screen.

7027

Invalid XML

Returned when an invalid XML request is sent.

Request Examples

{
    "expiry":"<expiry time in UTC format>",
    "notifyurl":"<Notification URL>",
    "events":[
        {
            "evtid":"<Event ID>",
            "correlationid":"<Unique transaction ID from the client end>",
            "parameters":
             {
                "param1":"value1",
                "param2":"value2"
                
             }
        }
      ]
}
{
    "expiry":"<expiry time in UTC format>",
    "notifyurl":"<Notification URL>",
    "events":[
        {
            "evtid":"<Event ID>",
            "correlationid":"<Correlation ID>",
            "parameters":
             {
                "param1":"value1",
                "param2":"value2"
              
             }
        },
        {
            "evtid":"<Event ID>",
            "correlationid":"<Correlation ID>",
            "parameters":
             {
                "param1":"value1",
                "param2":"value2"
               
             }
        }
    ]
}

Response Example

{
  "response":{
           "code":"<Status code>",
            "description" : "<Description of status code>",
            "transid":"< Transaction ID generated by IMIconnect >",
            "correlationid":"<Correlation ID>",       
           
     }
   }
Suggest Edits

Custom Event v2

 
posthttps://hooks.imiconnect.io/events/<eventID>

Path Params

eventID
string
required

Available in the unique endpoint generated for every new custom event v2

Headers

Content-Type
string
required

application/json

key
string
required

Service Key - Only required if requires authentication is selected in custom event creaiton

 

Custom Event API V2

The new API creates a unique end point URL for each event that is created. As a result, it can accept any JSON (including nested) and parse it

When we parse JSON packets sent to us we flatten nested attributes and place a double underscore between them.

Authentication

If you want us to authenticate your inbound events then you can enable the 'Requires authentication' option. Once this is done, IMIconnect will only accept POST requests with key in the header which is the service key of the service in which the event is created

Once a new event is created, it can start accepting any JSON and all the parameters will be passed onto subsequent rules and flows

You can also enter example JSON or send a live request to parse. These parameters will be saved and available for usage in rules and flows when you start typing with $ to search for a variable.

Here is an example of how a smaple JSON is parsed.

{  
   "data":[  
      {  
         "type":"articles",
         "id":"1",
         "attributes":{  
            "title":"JSON API paints my bikeshed!",
            "body":"The shortest article. Ever.",
            "created":"2015-05-22T14:56:29.000Z",
            "updated":"2015-05-22T14:56:28.000Z"
         }
      }
   ]
}

Parsed variables

Parameter
Parsed value

data__type

articles

data__id

1

data__attributes__title

JSON API paints my bikeshed!

data__attributes__body

The shortest article. Ever.

data__attributes__created

2015-05-22T14:56:29.000Z

data__attributes__updated

2015-05-22T14:56:28.000Z

Suggest Edits

Overview

Profile API enable clients to manage their customer profiles.

 

A customer profile consists of a Master Profile and an Application Profile. The Master Profile consists of core attributes (such as the unique Customer ID, customer name, email address, and msisdn). Application Profile consists of channel specific information.

Prerequisites
To send and receive profile information via IMIconnect platform, following prerequisites should be met:

  • A client must be created on IMIconnect.
  • A Client Profile Key must be passed with every API request.
    For more information on profile key information, contact IMImobile.

The Profile API provides four functional groups that are prefixed with add, update, manage, and delete. The following table describes these groups.

HTTP Method
CRUD
Name
Description

GET

Read

Get profile specified by the customerid.

GET

Read

Retrieve customer application profile.

POST

Create

Create customer's master profile.

POST

Create

Create customer's application profile.

PUT

Update

Update customer's master profile.

PUT

Update

Update customer's application profile.

DELETE

Delete

Delete customer profile.

DELETE

Delete

Delete application profile.

DELETE

Delete

Delete device application profile.

API Parameters

Parameter
Use
Description

key

This parameter is passed in the header for all calls.

The Client Profile Key authenticates Profile API requests and must be passed with every request.

customerid

This parameter is passed as part of the URL in the following:

This parameter is passed as part of the REQUEST in the following:

This parameter is passed as part of the URL and REQUEST in the following:

The customerid is a Service Provider specific ID (such as CRN) to uniquely identify a customer.

A customer can add or remove communication services (e.g. Facebook, Twitter etc.) which are associated with their customerid.

This allows the IMIconnect platform to match the relevant customer communication ID based on the chosen communication service with the customerid.

showinwardlinks

This parameter is passed as part of the URL and REQUEST in the following:

Extended information within the customer profile in the InwardLinks section can be retrieved as part of the request. The InwardLinks section contains channel specific attributes that are linked to the customer profile (e.g. Facebook, Twitter etc.).

0 - Retrieve Master Profile only
1 - Retrieve Master Profile and Application Profile.
2 - Retrieve full profile.

attributes

This parameter is passed as part of the REQUEST in the following:

An array of strings that define a customer profile. This includes the following keys:

  • email
  • msidn

Service Providers may include their own keys.

appid

This parameter is passed as part of the URL in the following:

This parameter is passed as part of the REQUEST in the following:

This parameter is passed as part of the URL and REQUEST in the following:

Application ID that is associated with an application (e.g. Facebook, Twitter etc.).

appprofilekey

This parameter is passed as part of the URL in the following:

This parameter is passed as part of the REQUEST in the following:

This parameter is passed as part of the URL and REQUEST in the following:

Application Profile key. This will vary depending on the application (e.g. Facebook, Twitter, etc.,).

Response / Error Codes

Code
Message
Description

1000

Success

Returned when the request is completed successfully.

1002

Partial success

Returned when not all profiles were created or updated in a single request.

7000

Invalid JSON

Returned when an invalid JSON request is sent.

7001

Authentication failed

Returned when an invalid service key or profile key is provided in the request.

7002

Service Key Missing

Returns when profile key is missing in header

7003

Mandatory parameters missing

7004

Invalid parameters

7006

Internal error occurred

Returned when an internal error occurs.

7010

Source ip is not white listed

Returned when an API call is made from other than white listed IPs.

7012

Batch size limit(100) exceeded

Returned when the size of the batch exceeds the 100 requests.

7013

Master profile store not found

Returned when the master profile table is not found in the database.

7014

Customer not found

Returned when the customer profile does not exist.

7015

Customer already exists

Returned when a customer profile is being created for which the profile already exists.

7016

Unknwon error

Returned when an unknown error occurred while trying to access profile APIs

7017

Profile attribute doesn't exist

Returned when there is an error in retrieving profile attributes or when the profile attributes do not exist in the database.

7018

invalid app profile or app profile is not linked to this client

Returned when trying to retrieve invalid profile in the app.

7020

You have reached maximum transaction limit

Returned when a user reaches maximum transaction limit for accessing API.

7203

Customer/App not found

Returned when a customer or application does not exists to update or delete the profile.

7205

Invalid attribute value

Returned when an invalid value is provided for the customer or app profile Attributes object.

7206

Master profile store not found

Returned when a master profile store does not exists.

7207

Batch size limit (100) exceeded

Returned when an API request exceeds the limit to create or update or delete using profile API.

7209

Customer/App profile already exists

Returned when a customer or application profile is being created for which the profile already exists.

7211

Profile attribute does not exist

Returned when an attribute is sent for which the attribute is not defined in client master profile.

7212

Invalid app profile or app profile not linked to this client.

Returned when an application master profile does not exists.

Suggest Edits

Create Profile

This API is used create a customer's profile.

 
posthttps://api.imiconnect.io/resources/v2/customerprofile
 

Request

The Create Profile request is specified as follows:

Request Headers

The following table describes the request headers:

Request Header
Description

key

Client profile key

content-type

application/json

Request Body

The following table describes the elements in the request body:

Parameter
Type
Mandatory
Description

customerId

String

Yes

A client specific ID (such as CRN) to uniquely identify a customer.

attributes

JSONObject

Yes

The attributes that are selected while creating a client from IMIconnect admin.

Status Codes

This API may return the following response codes:

Response Code
Message
Description

1000

Queued

Returned when the request is queued.

7000

invalid JSON

Returned when an invalid JSON request is sent.

7001

Authentication failed

Returned when an invalid service key or profile key is provided in the request.

7002

Service Key Missing

Returned when the parameter key is missing in the message request.

7003

Mandatory parameters missing

7006

Internal error occurred

Returned when an internal error occurs in IMIconnect.

7010

Source IP is not white listed

Returned when a request is sent from an IP that is not whitelisted in IMIconnect.

7011

Invalid Attribute Value

Returned when an invalid value is provided for the customer or app profile Attributes object.

7012

Batch size limit(100) exceeded

Returned when an API request exceeds the limit to create or update or delete using profile API.

7015

customer already exists

Returned when a customer or app profile already exists.

Request Example

{
  "Records": [
    {
      "customerId": "54321",
      "Attributes": {
        "email": "test1@imimobile.com",
        "msisdn": "911278994640",
        "name": "John"
      }
    },
    {
      "customerId": "54322",
      "Attributes": {
        "email": "test2@imimobile.com",
        "msisdn": "911278994642",
        "name": "Gary"
      }
    }
  ]
}
{
  "Records": [
    {
      "customerId": "54321",
      "Attributes": {
        "email": "test1@imimobile.com",
        "msisdn": "911278994640",
        "name": "John"
      }
    }
  ]
}

Response Example

{
   "FailureCount":0,
   "TotalCount":2,
   "description":"QUEUED",
   "SuccessCount":2,
   "code":"1000",
   "Results":[
      {
         "customerId":"54321",
         "description":"QUEUED",
         "code":"1000"
      },
      {
         "customerId":"54322",
         "description":"QUEUED",
         "code":"1000"
      }
   ],
   "transid":"51548494-4c4d-46b6-9abf-d8f881e85e1f"
}
{
   "FailureCount":0,
   "TotalCount":1,
   "description":"SUCCESS",
   "SuccessCount":1,
   "code":"1000",
   "Results":[
      {
         "customerId":"54321",
         "description":"SUCCESS",
         "code":"1000"
      }
   ],
   "transid":"51548494-4c4d-46b6-9abf-d8f881e85e1f"
}
Suggest Edits

Create App Profile

This API is used to create customer's application profile.

 
posthttps://api.imiconnect.io/resources/v2/customerappprofile/<appid>
 

Request

The create app profile request is specified as follows:

URI

https://api.imiconnect.com/resources/v2/customerappprofile/<appid>


appid: Specifies the application id.

Method

POST

Request Headers

The following table describes the request headers:

Request Header
Description

key

Client profile key

content-type

application/json

Request Body

The following table describes the elements in the request body:

Parameter
Type
Mandatory
Description

customerid

String

Yes

Customer ID is a Client specific ID (such as CRN) to uniquely identify a customer.

attributes

JSONObject

Yes

Key value pairs to add.
 
Facebook:

  • status
  • verified
  • psid
  • customerId
  • name
  • profile_pic
  • gender
  • locale
  • timezone
  • channel
  • createdOn
  • updatedOn

 
Twitter:

  • status
  • verified
  • twitterid
  • twitter_handle
  • twitter_name
  • customerId
  • geolocation
  • timezone
  • channel
  • createdOn
  • updatedOn

 
WeChat:

  • customerId
  • city
  • verified
  • createdOn
  • nick
  • status
  • gender
  • province
  • language
  • country
  • created_on
  • updated_on

 
In-App:

  • status
  • verified
  • customerId
  • connectStatus
  • appId
  • userId
  • password
  • deviceId
  • batterylevel
  • Bluetooth
  • cellid
  • connectType
  • email
  • externalmemory
  • foreground
  • foregroundapp
  • idlescreen
  • imei
  • imsi
  • internalmemory
  • IP
  • language
  • oldlocation
  • location
  • MAC
  • make HTC
  • MCC
  • MNC
  • model
  • NFC
  • os
  • osversion
  • phonemode
  • presence
  • RAM
  • resolution
  • roaming
  • serialnumber
  • signalstrength
  • teleco
  • timespent
  • timezone
  • useragent
  • pushId
  • createdOn
  • last_opened
  • last_upgraded
  • channel
  • accounts
  • sdkversion

 
Push:

  • status
  • verified
  • customerId
  • connectStatus
  • appId
  • userId
  • password
  • deviceId
  • batterylevel
  • Bluetooth
  • cellid
  • connectType
  • email
  • externalmemory
  • foreground
  • foregroundapp
  • idlescreen
  • imei
  • imsi
  • internalmemory
  • IP
  • language
  • oldlocation
  • location
  • MAC
  • make HTC
  • MCC
  • MNC
  • model
  • NFC
  • os
  • osversion
  • phonemode
  • presence
  • RAM
  • resolution
  • roaming
  • serialnumber
  • signalstrength
  • teleco
  • timespent
  • timezone
  • useragent
  • pushId
  • createdOn
  • last_opened
  • last_upgraded
  • channel
  • accounts
  • sdkversion

Profile details are encapsulated within the Attributes section. Additional key value pairs may be added as required.

Status Codes

This API may return the following response codes:

Response Code
Message
Description

1000

Queued

Returned when the request is queued.

1002

Partial success

Returned when at least one app profile could not be created successfully.

7000

Invalid JSON

Returned when an invalid JSON request is sent.

7001

Authentication failed

Returned when the invalid service key or profile key is provided in the request.

7002

Service Key Missing

Returned when the parameter key is missing in the message request.

7003

Mandatory parameters missing

7006

Internal error occurred

Returned when an internal error occurs.

7010

Source IP is not white listed

Returned when a request is sent from an IP that is not whitelisted in IMIconnect.

7011

Invalid Attribute Value

Returned when an invalid value is provided for the customer or app profile Attributes object.

7018

invalid app profile or app profile is not linked to this client

Returned when an application master profile does not exists.

Request Examples

{
    "Records": [{
        "customerId": "8955",
        "Attributes": {
            "status": "1",
						"verified": "1",
						"psid": "1652750724851329",
						"createdOn": "2018-08-26 12:26:03",
						"customerId": "1842"
						"name": "Ravipudi Durgaprasad",
						"profile_pic": "https://platform-lookaside.fbsbx.com/platform/profilepic/?							 psid=1652750724851329&width=1024&ext=1537878362&hash=AeQ6XJBhDeMC7RUN",
						"gender": "male",
						"locale": "en_US",
						"timezone": "5.5",
						"channel": "fb",
						"updatedOn": "2018-09-19 07:13:50"

        }
    },
                {
        "customerId": "8956",
        "Attributes": {
            "status": "1",
						"verified": "1",
						"psid": "1652750724851134",
						"createdOn": "2018-08-26 12:26:03",
						"customerId": "1845"
						"name": "Anil Dhar",
						"profile_pic": "https://platform-lookaside.fbsbx.com/platform/profilepic/?							 psid=1652750724851329&width=1024&ext=1537878362&hash=AeQ6XJBhDeMC7RUN",
						"gender": "male",
						"locale": "en_US",
						"timezone": "5.5",
						"channel": "fb",
						"updatedOn": "2018-09-25 07:14:35"        }
    }]
}
{
    "Records": [{
        "customerId": "8957",
        "Attributes": {
            "status": "1",
						"verified": "1",
						"twitterid": "3424284794",
						"twitter_handle": "BalajiSatuluri",
						"twitter_name": "Balaji Satuluri",
						"customerId": "3330",
						"geolocation": "",
						"timezone": "",
						"channel": "twitter",
						"createdOn": "2016-10-14 05:27:50",
						"updatedOn": "2018-09-19 07:07:29"

        }
    }]
{
    "Records": [{
        "customerId": "9876",
        "Attributes": {
            "created_on": ISODate('2018-04-02T07:09:30.395Z'),
						"updated_on": ISODate('2018-04-02T07:25:22.660Z'),
						"customerId": "8953",
						"city": "",
						"verified": "2018-04-02T07:25:22.660Z",
						"createdOn": "2018-04-02T06:09:30.611Z",
						"nick": "cogniti",
						"status": "1",
						"gender": "Female",
						"province": "",
						"language": "en",
						"country": "India"
        } 
    },
               {
        "customerId": "9877",
        "Attributes": {
            "created_on": ISODate('2018-04-02T07:10:30.395Z'),
						"updated_on": ISODate('2018-04-02T08:26:22.660Z'),
						"customerId": "8954",
						"city": "",
						"verified": "2018-05-02T07:25:23.660Z",
						"createdOn": "2018-05-02T06:09:30.611Z",
						"nick": "cogniti",
						"status": "1",
						"gender": "Female",
						"province": "",
						"language": "en",
						"country": "India"
        }
    }
               ]
}
{
    "Records": [{
        "customerId": "9879",
        "Attributes": {
						"status": "",
						"verified": "0",
						"customerId": "0774943838490264760"
          	"connectStatus": "1",
						"appId": "",
						"userId": "30774943838490264760",
						"password": "",
            "deviceId": "HT59TBE00192",
            "batterylevel": "",
            "Bluetooth": "",
            "cellid": "",
            "connectType": "",
            "email": "",
            "externalmemory": "",
            "foreground": "",
            "foregroundapp": "",
            "idlescreen": "",
            "imei": "",
            "imsi": "",
            "internalmemory": "",
            "IP": "",
            "language": "",
            "oldlocation": "[]",
            "location": "",
            "MAC": "",
            "make": "HTC",
            "MCC": "",
            "MNC": "",
            "model": "HTC One A9",
            "NFC": "",
            "os": "Android",
            "osversion": "6.0.1",
            "phonemode": "",
            "presence": "",
            "RAM": "",
            "resolution": "",
            "roaming": "",
            "serialnumber": "",
            "signalstrength": "",
            "teleco": "",
            "timespent": "",
            "timezone": "",
            "useragent": "",
            "pushId": "fwYj0eb9jmM:APA91bF3hHgNR51OgRJ64dC2bmHa3Hh6BWHjSnDCv4ZFfvSgEiCx0p6bqeB0Ij9DdAy41t275Hhd02TC6BufvakJimEuGw_68nyUA9JWZXGylmfSkcC_2RSsys3yR6HLvZgu8esif_jd",
            "rtmId": "30774943838490264760_HT59TBE00192",
            "createdOn": "2018-09-11 15:37:28",
            "last_opened": "2018-09-12T10:24:59.907Z",
            "last_upgraded": "2018-09-11T15:37:29.067Z",
            "channel": "rt",
            "accounts": "",
            "sdkversion": "",
        }
    }]
}
{
    "Records": [{
        "customerId": "9879",
        "Attributes": {
						"status": "",
						"verified": "0",
						"customerId": "0774943838490264760"
						"connectStatus": "1",
						"appId": "",
						"userId": "30774943838490264760",
						"password": "",
            "deviceId": "HT59TBE00192",
            "batterylevel": "",
            "Bluetooth": "",
            "cellid": "",
            "connectType": "",
            "email": "",
            "externalmemory": "",
            "foreground": "",
            "foregroundapp": "",
            "idlescreen": "",
            "imei": "",
            "imsi": "",
            "internalmemory": "",
            "IP": "",
            "language": "",
            "oldlocation": "[]",
            "location": "",
            "MAC": "",
            "make": "HTC",
            "MCC": "",
            "MNC": "",
            "model": "HTC One A9",
            "NFC": "",
            "os": "Android",
            "osversion": "6.0.1",
            "phonemode": "",
            "presence": "",
            "RAM": "",
            "resolution": "",
            "roaming": "",
            "serialnumber": "",
            "signalstrength": "",
            "teleco": "",
            "timespent": "",
            "timezone": "",
            "useragent": "",
            "pushId": "fwYj0eb9jmM:APA91bF3hHgNR51OgRJ64dC2bmHa3Hh6BWHjSnDCv4ZFfvSgEiCx0p6bqeB0Ij9DdAy41t275Hhd02TC6BufvakJimEuGw_68nyUA9JWZXGylmfSkcC_2RSsys3yR6HLvZgu8esif_jd",
            "rtmId": "30774943838490264760_HT59TBE00192",
            "createdOn": "2018-09-11 15:37:28",
            "last_opened": "2018-09-12T10:24:59.907Z",
            "last_upgraded": "2018-09-11T15:37:29.067Z",
            "channel": "rt",
            "accounts": "",
            "sdkversion": "",
        }
    }]
}

Response Examples

{
    "FailureCount": 1,
    "TotalCount": 1,
    "description": "QUEUED",
    "SuccessCount": 1,
    "code": "1000",
    "Results": [
        {
            "customerId": "8955",
            "description": "QUEUED",
            "code": "1000"
        },
      {
            "customerId": "8956",
            "description": "QUEUED",
            "code": "1000"
        }
    ],
    "transid": "29a70681-43ea-44c0-9423-5fe4567f5cbb"
}
{
    "FailureCount": 1,
    "TotalCount": 1,
    "description": "QUEUED",
    "SuccessCount": 1,
    "code": "1000",
    "Results": [
        {
            "customerId": "8957",
            "description": "QUEUED",
            "code": "1000"
        }
    ],
    "transid": "29a70681-43ea-44c0-9423-5fe4567f5cbb"
}
{
    "FailureCount": 1,
    "TotalCount": 1,
    "description": "QUEUED",
    "SuccessCount": 1,
    "code": "1000",
    "Results": [
        {
            "customerId": "9876",
            "description": "QUEUED",
            "code": "1000"
        },
       {
            "customerId": "9877",
            "description": "QUEUED",
            "code": "1000"
        }
    ],
    "transid": "29a70681-43ea-44c0-9423-5fe4567f5cbb"
}
{
    "FailureCount": 1,
    "TotalCount": 1,
    "description": "QUEUED",
    "SuccessCount": 1,
    "code": "1000",
    "Results": [
        {
            "customerId": "9879",
            "description": "QUEUED",
            "code": "1000"
        }
    ],
    "transid": "29a70681-43ea-44c0-9423-5fe4567f5cbb"
}
Suggest Edits

Get Profile

This API is used to retrieve the profile of a single customer or multiple customers.

 
gethttps://api.imiconnect.io/resources/v1/customerprofile/<customerid>
 

Request

The get profile request is specified as follows:

URI

https://api.imiconnect.io/resources/v1/customerprofile/<customerid>

customerid: A client specific ID (such as CRN) to uniquely identify a customer.

Method

GET

URI Parameters

Parameter
Description

showinwardlinks

Extended information within the customer profile in the inwardlinks section can be retrieved as part of the request. The inwardlink section contains channel specific attributes that are linked to the customer profile (e.g. Facebook and Twitter etc.). The values are:

0: Retrieve master profile only.
1: Retrieve master profile and application profiles.
2: Retrieve full profile.

Request Headers

The following table describes the request headers:

Request Header
Description

key

Client profile key

content-type

application/json

Request Body

The following table describes the elements in the request URL:

Parameter
Type
Mandatory
Description

customerid

String

Yes

A client specific ID (such as CRN) to uniquely identify a customer.

Status Codes

This API may return the following response codes:

Response Code
Message
Description

1000

Success

Returned when the request is completed successfully.

7000

Invalid JSON

Returned when an invalid JSON request is sent.

7001

Authentication failed

Returned when the invalid service key or profile key is provided in the request.

7003

Mandatory parameters missing

Request Example

https://api.imiconnect.com/resources/v1/customerprofile/4545?showinwardlinks=0
https://api.imiconnect.com/resources/v1/customerprofile?customerId=2134&customerId=2142&showinwardlinks=0

Response Examples

{
  "Status": 0,
  "Description": "success",
  "Records": [
    {
      "Attributes": [
        {
          "Name": "msisdn",
          "Value": "91900007707",
          "ID": 8574
        },
        {
          "Name": "email",
          "Value": "John.g@gmail.com",
          "ID": 8575
        },
        {
          "Name": "name",
          "Value": "john",
          "ID": 8576
        },
        {
          "Name": "customerId",
          "Value": "4545",
          "ID": 8577
        },
        {
          "Name": "sms",
          "Value": "1",
          "ID": 8578
        },
        {
          "Name": "voice",
          "Value": "1",
          "ID": 8579
        },
        {
          "Name": "rt",
          "Value": "1",
          "ID": 8580
        },
        {
          "Name": "fb",
          "Value": "1",
          "ID": 8581
        },
        {
          "Name": "twitter",
          "Value": "1",
          "ID": 8582
        },
        {
          "Name": "wechat",
          "Value": "1",
          "ID": 8583
        },
        {
          "Name": "wa",
          "Value": "1",
          "ID": 8584
        }
      ],
      "InwardLinks": [],
      "OutwardLinks": []
    }
  ],
  "code": "1000",
  "transid": "d2708309-75ab-4f18-b5c6-3f23ab9afd43"
}
{
    "Status": 0,
    "Description": "success",
    "Records": [{
        "Attributes": [{
            "Name": "msisdn",
            "Value": "918106565495",
            "ID": 8328
        }, {
            "Name": "email",
            "Value": "jagadeesh.t@imimobile.com",
            "ID": 8329
        }, {
            "Name": "name",
            "Value": "jagadeesh",
            "ID": 8330
        }, {
            "Name": "customerId",
            "Value": "2134",
            "ID": 8331
        }, {
            "Name": "sms",
            "Value": "1",
            "ID": 8332
        }, {
            "Name": "voice",
            "Value": "1",
            "ID": 8333
        }, {
            "Name": "ussd",
            "Value": "1",
            "ID": 8334
        }, {
            "Name": "rt",
            "Value": "1",
            "ID": 8335
        }, {
            "Name": "fb",
            "Value": "1",
            "ID": 8336
        }, {
            "Name": "fbc",
            "Value": "1",
            "ID": 8337
        }, {
            "Name": "twitter",
            "Value": "1",
            "ID": 8338
        }, {
            "Name": "mxit",
            "Value": "1",
            "ID": 8339
        }, {
            "Name": "wechat",
            "Value": "1",
            "ID": 8340
        }, {
            "Name": "wa",
            "Value": "1",
            "ID": 8341
        }],
        "InwardLinks": [],
        "OutwardLinks": []
    }, {
        "Attributes": [{
            "Name": "msisdn",
            "Value": "919963427038",
            "ID": 8328
        }, {
            "Name": "email",
            "Value": "balaji.s@imimobile.com",
            "ID": 8329
        }, {
            "Name": "name",
            "Value": "balaji",
            "ID": 8330
        }, {
            "Name": "customerId",
            "Value": "2142",
            "ID": 8331
        }, {
            "Name": "sms",
            "Value": "1",
            "ID": 8332
        }, {
            "Name": "voice",
            "Value": "1",
            "ID": 8333
        }, {
            "Name": "ussd",
            "Value": "1",
            "ID": 8334
        }, {
            "Name": "rt",
            "Value": "1",
            "ID": 8335
        }, {
            "Name": "fb",
            "Value": "1",
            "ID": 8336
        }, {
            "Name": "fbc",
            "Value": "1",
            "ID": 8337
        }, {
            "Name": "twitter",
            "Value": "1",
            "ID": 8338
        }, {
            "Name": "mxit",
            "Value": "1",
            "ID": 8339
        }, {
            "Name": "wechat",
            "Value": "1",
            "ID": 8340
        }, {
            "Name": "wa",
            "Value": "1",
            "ID": 8341
        }],
        "InwardLinks": [],
        "OutwardLinks": []
    }],
    "code": "1000",
    "transid": "236fe39b-78b0-4f94-bcda-270cdd01ab9a"
}
Suggest Edits

Get App Profile

This API is used to retrieve a customer's application profile for a given appid and customer profile key. The appid is a unique ID for individual channel assets.

 
gethttps://api.imiconnect.io/resources/v1/customerappprofile/<appid>/<customerid>
 

Request

The get app profile request is specified as follows:

URI

https://api.imiconnect.io/resources/v1/customerappprofile/<appid>/<customerid>


appid: Specifies the application id.
customerid: A client specific ID (such as CRN) to uniquely identify a customer.

Method

GET

Request Headers

The following table describes the request headers:

Request Header
Description

key

Client profile key

content-type

application/json

For data privacy and security reasons, the REST API is served over encrypted HTTPS. The standard HTTP is not supported.

Status Codes

This API may return the following response codes:

Response Code
Message
Description

1000

Success

Returned when the request is completed successfully.

7000

Invalid JSON

Returned when an invalid JSON request is sent.

7001

Authentication failed

Returned when the invalid service key or profile key is provided in the request.

7003

Mandatory parameters missing

Request Example

https://api.imiconnect.com/resources/v1/customerappprofile/a_636035705699961900/8953
https://api.imiconnect.com/resources/v1/customerappprofile/BO20055029?customerId=8953&customerId=8954

Response Examples

{
  "Status": 0,
  "Description": "success",
  "Records": [
    {
      "Attributes": [
        {
          "Name": "status",
          "Value": 1,
          "ID": 16528
        },
        {
          "Name": "verified",
          "Value": 1,
          "ID": 16529
        },
        {
          "Name": "twitterid",
          "Value": "3223165326",
          "ID": 16530
        },
        {
          "Name": "twitter_handle",
          "Value": "wsophyd3",
          "ID": 16531
        },
        {
          "Name": "twitter_name",
          "Value": "Jack",
          "ID": 16532
        },
        {
          "Name": "customerId",
          "Value": "8953",
          "ID": 16533
        },
        {
          "Name": "geolocation",
          "Value": "",
          "ID": 16534
        },
        {
          "Name": "timezone",
          "Value": "Pacific Time (US & Canada)",
          "ID": 16535
        },
        {
          "Name": "channel",
          "Value": "twitter",
          "ID": 16536
        },
        {
          "Name": "createdOn",
          "Value": "2016-07-08 10:49:20",
          "ID": 16537
        },
        {
          "Name": "updatedOn",
          "Value": "2016-07-13 08:19:31",
          "ID": 16538
        }
      ],
      "InwardLinks": [],
      "OutwardLinks": [
        {
          "Records": [
            [
              {
                "Name": "msisdn",
                "Value": "919908505526",
                "ID": 8574
              },
              {
                "Name": "email",
                "Value": "john.m@imimobile.com",
                "ID": 8575
              },
              {
                "Name": "name",
                "Value": "john",
                "ID": 8576
              },
              {
                "Name": "customerId",
                "Value": "8953",
                "ID": 8577
              },
              {
                "Name": "sms",
                "Value": "1",
                "ID": 8578
              },
              {
                "Name": "voice",
                "Value": "1",
                "ID": 8579
              },
              {
                "Name": "rt",
                "Value": "1",
                "ID": 8580
              },
              {
                "Name": "fb",
                "Value": "1",
                "ID": 8581
              },
              {
                "Name": "twitter",
                "Value": "1",
                "ID": 8582
              },
              {
                "Name": "wechat",
                "Value": "1",
                "ID": 8583
              },
              {
                "Name": "wa",
                "Value": "1",
                "ID": 8584
              }
            ]
          ],
          "ProfileID": 341,
          "ProfileName": "UKREG42_cpms_1"
        }
      ]
    }
  ],
  "code": "1000",
  "transid": "c01bea92-6fc6-4416-b1da-79f15a19fd0c"
}
{
  "Status": 0,
  "Description": "success",
  "Records": [
    {
      "Attributes": [
        {
          "Name": "status",
          "Value": 0,
          "ID": 6063
        },
        {
          "Name": "verified",
          "Value": "0",
          "ID": 6064
        },
        {
          "Name": "customerId",
          "Value": "8954",
          "ID": 6065
        },
        {
          "Name": "connectStatus",
          "Value": 0,
          "ID": 6066
        },
        {
          "Name": "appId",
          "Value": "",
          "ID": 6067
        },
        {
          "Name": "userId",
          "Value": "8954",
          "ID": 6068
        },
        {
          "Name": "password",
          "Value": "",
          "ID": 6069
        },
        {
          "Name": "deviceId",
          "Value": "",
          "ID": 6070
        },
        {
          "Name": "batterylevel",
          "Value": "11%",
          "ID": 6071
        },
        {
          "Name": "Bluetooth",
          "Value": "1",
          "ID": 6072
        },
        {
          "Name": "cellid",
          "Value": "",
          "ID": 6073
        },
        {
          "Name": "connectType",
          "Value": "",
          "ID": 6074
        },
        {
          "Name": "email",
          "Value": "",
          "ID": 6075
        },
        {
          "Name": "externalmemory",
          "Value": "",
          "ID": 6076
        },
        {
          "Name": "foreground",
          "Value": "0",
          "ID": 6077
        },
        {
          "Name": "foregroundapp",
          "Value": "",
          "ID": 6078
        },
        {
          "Name": "idlescreen",
          "Value": "",
          "ID": 6079
        },
        {
          "Name": "imei",
          "Value": "",
          "ID": 6080
        },
        {
          "Name": "imsi",
          "Value": "",
          "ID": 6081
        },
        {
          "Name": "internalmemory",
          "Value": "11.85 GB",
          "ID": 6082
        },
        {
          "Name": "IP",
          "Value": "192.168.1.2",
          "ID": 6083
        },
        {
          "Name": "language",
          "Value": "English (en-IN)",
          "ID": 6084
        },
        {
          "Name": "oldlocation",
          "Value": "[ { \"val\" : \"[17.40209177851416,78.48741864001678]\" , \"count\" : 1 , \"trans_date\" : { \"$date\" : \"2016-02-22T19:07:49.714Z\"}}]",
          "ID": 6085
        },
        {
          "Name": "location",
          "Value": "[17.4026309524199,78.48846396756929]",
          "ID": 6086
        },
        {
          "Name": "MAC",
          "Value": "",
          "ID": 6087
        },
        {
          "Name": "make",
          "Value": "Apple",
          "ID": 6088
        },
        {
          "Name": "MCC",
          "Value": "",
          "ID": 6089
        },
        {
          "Name": "MNC",
          "Value": "",
          "ID": 6090
        },
        {
          "Name": "model",
          "Value": "iPhone 6 (GSM+CDMA)",
          "ID": 6091
        },
        {
          "Name": "NFC",
          "Value": "",
          "ID": 6092
        },
        {
          "Name": "os",
          "Value": "ios",
          "ID": 6093
        },
        {
          "Name": "osversion",
          "Value": "9.2.1",
          "ID": 6094
        },
        {
          "Name": "phonemode",
          "Value": "",
          "ID": 6095
        },
        {
          "Name": "presence",
          "Value": "",
          "ID": 6096
        },
        {
          "Name": "RAM",
          "Value": "1.00 GB",
          "ID": 6097
        },
        {
          "Name": "resolution",
          "Value": "750x1334",
          "ID": 6098
        },
        {
          "Name": "roaming",
          "Value": "",
          "ID": 6099
        },
        {
          "Name": "serialnumber",
          "Value": "",
          "ID": 6100
        },
        {
          "Name": "signalstrength",
          "Value": "",
          "ID": 6101
        },
        {
          "Name": "teleco",
          "Value": "",
          "ID": 6102
        },
        {
          "Name": "timespent",
          "Value": 385,
          "ID": 6103
        },
        {
          "Name": "timezone",
          "Value": "",
          "ID": 6104
        },
        {
          "Name": "useragent",
          "Value": "Mozilla/5.0 (iPhone; CPU iPhone OS 9_2_1 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Mobile/13D15",
          "ID": 6105
        },
        {
          "Name": "pushId",
          "Value": "6682513c1a97730fb9b69e1358273571fa5181e930bc37b9f905adead18322d3",
          "ID": 6106
        },
        {
          "Name": "rtmId",
          "Value": "8954_08519E2437BB40FEBDF694B5C88703DC",
          "ID": 6107
        },
        {
          "Name": "createdOn",
          "Value": "2016-08-09 12:57:26",
          "ID": 6108
        },
        {
          "Name": "last_opened",
          "Value": "2016-02-22T18:38:57+0530",
          "ID": 6109
        },
        {
          "Name": "last_upgraded",
          "Value": "2016-02-18T20:24:11+0530",
          "ID": 6110
        },
        {
          "Name": "channel",
          "Value": "rt",
          "ID": 6111
        }
      ],
      "InwardLinks": [],
      "OutwardLinks": [
        {
          "Records": [
            [
              {
                "Name": "msisdn",
                "Value": "918019031470",
                "ID": 5950
              },
              {
                "Name": "email",
                "Value": "chaitanya.marella@imimobile.com",
                "ID": 5951
              },
              {
                "Name": "name",
                "Value": "Chaitanya",
                "ID": 5952
              },
              {
                "Name": "customerId",
                "Value": "8954",
                "ID": 5953
              },
              {
                "Name": "country",
                "Value": "1",
                "ID": 5954
              },
              {
                "Name": "city",
                "Value": "1",
                "ID": 5955
              },
              {
                "Name": "sms",
                "Value": "1",
                "ID": 5956
              },
              {
                "Name": "voice",
                "Value": "1",
                "ID": 5957
              },
              {
                "Name": "ussd",
                "Value": "1",
                "ID": 5958
              },
              {
                "Name": "rt",
                "Value": "1",
                "ID": 5959
              },
              {
                "Name": "fb",
                "Value": "1",
                "ID": 5960
              },
              {
                "Name": "fbc",
                "Value": "1",
                "ID": 5961
              },
              {
                "Name": "twitter",
                "Value": "1",
                "ID": 5962
              },
              {
                "Name": "wechat",
                "Value": "1",
                "ID": 5963
              },
              {
                "Name": "wa",
                "Value": "1",
                "ID": 5964
              }
            ]
          ],
          "ProfileID": 239,
          "ProfileName": "UK412_cpms_1"
        }
      ]
    },
    {
      "Attributes": [
        {
          "Name": "status",
          "Value": 0,
          "ID": 6063
        },
        {
          "Name": "verified",
          "Value": "0",
          "ID": 6064
        },
        {
          "Name": "customerId",
          "Value": "8953",
          "ID": 6065
        },
        {
          "Name": "connectStatus",
          "Value": 0,
          "ID": 6066
        },
        {
          "Name": "appId",
          "Value": "",
          "ID": 6067
        },
        {
          "Name": "userId",
          "Value": "8953",
          "ID": 6068
        },
        {
          "Name": "password",
          "Value": "",
          "ID": 6069
        },
        {
          "Name": "deviceId",
          "Value": "08519E2437BB40FEBDF694B5C88703DC",
          "ID": 6070
        },
        {
          "Name": "batterylevel",
          "Value": "56%",
          "ID": 6071
        },
        {
          "Name": "Bluetooth",
          "Value": "1",
          "ID": 6072
        },
        {
          "Name": "cellid",
          "Value": "",
          "ID": 6073
        },
        {
          "Name": "connectType",
          "Value": "",
          "ID": 6074
        },
        {
          "Name": "email",
          "Value": "",
          "ID": 6075
        },
        {
          "Name": "externalmemory",
          "Value": "",
          "ID": 6076
        },
        {
          "Name": "foreground",
          "Value": "0",
          "ID": 6077
        },
        {
          "Name": "foregroundapp",
          "Value": "",
          "ID": 6078
        },
        {
          "Name": "idlescreen",
          "Value": "",
          "ID": 6079
        },
        {
          "Name": "imei",
          "Value": "",
          "ID": 6080
        },
        {
          "Name": "imsi",
          "Value": "",
          "ID": 6081
        },
        {
          "Name": "internalmemory",
          "Value": "11.85 GB",
          "ID": 6082
        },
        {
          "Name": "IP",
          "Value": "10.0.3.199",
          "ID": 6083
        },
        {
          "Name": "language",
          "Value": "English (en-IN)",
          "ID": 6084
        },
        {
          "Name": "oldlocation",
          "Value": "[ { \"val\" : \"[17.43485703226193,78.39852736587122]\" , \"count\" : 1 , \"trans_date\" : { \"$date\" : \"2016-03-02T06:10:57.449Z\"}}]",
          "ID": 6085
        },
        {
          "Name": "location",
          "Value": "[17.43586970339053,78.39709874994861]",
          "ID": 6086
        },
        {
          "Name": "MAC",
          "Value": "",
          "ID": 6087
        },
        {
          "Name": "make",
          "Value": "Apple",
          "ID": 6088
        },
        {
          "Name": "MCC",
          "Value": "404",
          "ID": 6089
        },
        {
          "Name": "MNC",
          "Value": "49",
          "ID": 6090
        },
        {
          "Name": "model",
          "Value": "iPhone 6 (GSM+CDMA)",
          "ID": 6091
        },
        {
          "Name": "NFC",
          "Value": "",
          "ID": 6092
        },
        {
          "Name": "os",
          "Value": "ios",
          "ID": 6093
        },
        {
          "Name": "osversion",
          "Value": "9.2.1",
          "ID": 6094
        },
        {
          "Name": "phonemode",
          "Value": "",
          "ID": 6095
        },
        {
          "Name": "presence",
          "Value": "",
          "ID": 6096
        },
        {
          "Name": "RAM",
          "Value": "1.00 GB",
          "ID": 6097
        },
        {
          "Name": "resolution",
          "Value": "750x1334",
          "ID": 6098
        },
        {
          "Name": "roaming",
          "Value": "0",
          "ID": 6099
        },
        {
          "Name": "serialnumber",
          "Value": "",
          "ID": 6100
        },
        {
          "Name": "signalstrength",
          "Value": "",
          "ID": 6101
        },
        {
          "Name": "teleco",
          "Value": "AirTel",
          "ID": 6102
        },
        {
          "Name": "timespent",
          "Value": 4242,
          "ID": 6103
        },
        {
          "Name": "timezone",
          "Value": "Asia/Kolkata",
          "ID": 6104
        },
        {
          "Name": "useragent",
          "Value": "Mozilla/5.0 (iPhone; CPU iPhone OS 9_2_1 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Mobile/13D15",
          "ID": 6105
        },
        {
          "Name": "pushId",
          "Value": "cf81c1b537de65fb26bc023f83008a6594fb74f9c8c96482a4427e9289bed217",
          "ID": 6106
        },
        {
          "Name": "rtmId",
          "Value": "8953_08519E2437BB40FEBDF694B5C88703DC",
          "ID": 6107
        },
        {
          "Name": "createdOn",
          "Value": "2016-08-09 12:57:26",
          "ID": 6108
        },
        {
          "Name": "last_opened",
          "Value": "2016-03-02T11:12:09+0530",
          "ID": 6109
        },
        {
          "Name": "last_upgraded",
          "Value": "2016-03-02T11:12:09+0530",
          "ID": 6110
        },
        {
          "Name": "channel",
          "Value": "rt",
          "ID": 6111
        }
      ],
      "InwardLinks": [],
      "OutwardLinks": [
        {
          "Records": [
            [
              {
                "Name": "msisdn",
                "Value": "919908505526",
                "ID": 5950
              },
              {
                "Name": "email",
                "Value": "chaitanya.marella@imimobile.com",
                "ID": 5951
              },
              {
                "Name": "name",
                "Value": "Chaitanya",
                "ID": 5952
              },
              {
                "Name": "customerId",
                "Value": "8953",
                "ID": 5953
              },
              {
                "Name": "country",
                "Value": "1",
                "ID": 5954
              },
              {
                "Name": "city",
                "Value": "1",
                "ID": 5955
              },
              {
                "Name": "sms",
                "Value": "1",
                "ID": 5956
              },
              {
                "Name": "voice",
                "Value": "1",
                "ID": 5957
              },
              {
                "Name": "ussd",
                "Value": "1",
                "ID": 5958
              },
              {
                "Name": "rt",
                "Value": "1",
                "ID": 5959
              },
              {
                "Name": "fb",
                "Value": "1",
                "ID": 5960
              },
              {
                "Name": "fbc",
                "Value": "1",
                "ID": 5961
              },
              {
                "Name": "twitter",
                "Value": "1",
                "ID": 5962
              },
              {
                "Name": "wechat",
                "Value": "1",
                "ID": 5963
              },
              {
                "Name": "wa",
                "Value": "1",
                "ID": 5964
              }
            ]
          ],
          "ProfileID": 239,
          "ProfileName": "UK412_cpms_1"
        }
      ]
    }
  ],
  "code": "1000",
  "transid": "67bcc0f8-6fef-4d1c-90e0-cfaaf3dafb63"
}
Suggest Edits

Get Profile Status

This API is used to retrieve the status of the profile create or updated.

 
gethttps://api.imiconnect.io/resources/v2/profile/status/transactionid

Path Params

transactionid
string
required

Transaction id of the created/updated profile request

Headers

key
string

Authentication for the API

 

Request

The get profile request is specified as follows:

URI

https://api.imiconnect.io/resources/v2/profile/status/bc83b74b-8ecf-473a-b938-db014f6aecdf

customerid: A client specific ID (such as CRN) to uniquely identify a customer.

Method

GET

Request Headers

The following table describes the request headers:

Request Header
Description

key

Client profile key

Response Header

The following table describes the elements in the request URL:

Parameter
Description

Content-Type

application/json

Status Codes

This API may return the following response codes:

Response Code
Message
Description

1000

Success

Returned when the request is completed successfully.

7600

No result found

Returned when an invalid transaction is sent.

Note: Request may be in queue, try once again after some time.

7001

Authentication failed

Returned when the invalid service key or profile key is provided in the request.

Request Example

https://api.imiconnect.io/resources/v2/profile/status/bc83b74b-8ecf-473a-b938-db014f6aecdf
https://api.imiconnect.com/resources/v1/customerprofile?customerId=2134&customerId=2142&showinwardlinks=0

Response Examples

{
    "TotalCount": 1,
    "code": "1000",
    "FailureCount": 0,
    "Results": [
        {
            "code": "1000",
            "customerId": "2021",
            "description": "SUCCESS"
        }
    ],
    "transid": "a61e8729-a404-41cc-909a-bf7de79d14c7",
    "description": "SUCCESS",
    "SuccessCount": 1
}
{
    "Status": 0,
    "Description": "success",
    "Records": [{
        "Attributes": [{
            "Name": "msisdn",
            "Value": "918106565495",
            "ID": 8328
        }, {
            "Name": "email",
            "Value": "jagadeesh.t@imimobile.com",
            "ID": 8329
        }, {
            "Name": "name",
            "Value": "jagadeesh",
            "ID": 8330
        }, {
            "Name": "customerId",
            "Value": "2134",
            "ID": 8331
        }, {
            "Name": "sms",
            "Value": "1",
            "ID": 8332
        }, {
            "Name": "voice",
            "Value": "1",
            "ID": 8333
        }, {
            "Name": "ussd",
            "Value": "1",
            "ID": 8334
        }, {
            "Name": "rt",
            "Value": "1",
            "ID": 8335
        }, {
            "Name": "fb",
            "Value": "1",
            "ID": 8336
        }, {
            "Name": "fbc",
            "Value": "1",
            "ID": 8337
        }, {
            "Name": "twitter",
            "Value": "1",
            "ID": 8338
        }, {
            "Name": "mxit",
            "Value": "1",
            "ID": 8339
        }, {
            "Name": "wechat",
            "Value": "1",
            "ID": 8340
        }, {
            "Name": "wa",
            "Value": "1",
            "ID": 8341
        }],
        "InwardLinks": [],
        "OutwardLinks": []
    }, {
        "Attributes": [{
            "Name": "msisdn",
            "Value": "919963427038",
            "ID": 8328
        }, {
            "Name": "email",
            "Value": "balaji.s@imimobile.com",
            "ID": 8329
        }, {
            "Name": "name",
            "Value": "balaji",
            "ID": 8330
        }, {
            "Name": "customerId",
            "Value": "2142",
            "ID": 8331
        }, {
            "Name": "sms",
            "Value": "1",
            "ID": 8332
        }, {
            "Name": "voice",
            "Value": "1",
            "ID": 8333
        }, {
            "Name": "ussd",
            "Value": "1",
            "ID": 8334
        }, {
            "Name": "rt",
            "Value": "1",
            "ID": 8335
        }, {
            "Name": "fb",
            "Value": "1",
            "ID": 8336
        }, {
            "Name": "fbc",
            "Value": "1",
            "ID": 8337
        }, {
            "Name": "twitter",
            "Value": "1",
            "ID": 8338
        }, {
            "Name": "mxit",
            "Value": "1",
            "ID": 8339
        }, {
            "Name": "wechat",
            "Value": "1",
            "ID": 8340
        }, {
            "Name": "wa",
            "Value": "1",
            "ID": 8341
        }],
        "InwardLinks": [],
        "OutwardLinks": []
    }],
    "code": "1000",
    "transid": "236fe39b-78b0-4f94-bcda-270cdd01ab9a"
}
Suggest Edits

Update Profile

This API is used to update one or more customer profiles. You can update up to 1000 customers in a single request.

 
puthttps://api.imiconnect.io/resources/v2/customerprofile
 

Request

The update profile request is specified as follows:

Request Headers

The following table describes the request headers:

Request Header
Description

key

Client profile key

content-type

application/json

For data privacy and security reasons, the REST API is served over encrypted HTTPS. Standard HTTP is not supported.

Request Body

The following table describes the elements in the request body:

Parameter
Type
Mandatory
Description

customerid

String

Yes

Customer ID is a Client specific ID (such as CRN) to uniquely identify a customer.

attributes

String

Yes

String of key/value pairs to add or update.

Response Codes

Following are the response codes this method may return:

Response Code
Message
Description

1000

Queued

Returned when the request is queued.

7000

Invalid JSON

Returned when an invalid service key or profile key is provided in the request.

7001

Authentication failed

Returned when an invalid service key or profile key is provided in the request.

7002

Service Key Missing

Returned when the parameter key is missing in the message request.

7003

Mandatory parameters missing

7006

Internal error occurred

Returned when an internal error occurs.

7010

Source ip is not white listed

Returned when a request is sent from an IP that is not whitelisted in IMIconnect.

7011

Invalid Attribute Value

Returned when an invalid value is provided for the customer or app profile Attributes object.

7012

Batch size limit(100) exceeded

Returned when an API request exceeds the limit to create or update or delete using profile API.

7014

Customer not found

Returned when a customer does not exists to update or delete the profile.

Request Examples

{
    "Records": [{
        "customerId": "1234568",
        "Attributes": {
            "email": "bulksmstest1@imimobile.com",
            "msisdn": "911278994640",
            "name": "umtest"
        }
    }, {
        "customerId": "1234569",
        "Attributes": {
            "email": "bulksmstest2@imimobile.com",
            "msisdn": "911278994642",
            "name": "umtest"
        }
    }]
}
{
    "Records": [{
        "customerId": "1234568",
        "Attributes": {
            "email": "bulksmstest1@imimobile.com",
            "msisdn": "911278994640",
            "name": "umtest"
        }
    }]
}

Response Examples

{
    "FailureCount": 0,
    "TotalCount": 2,
    "description": "QUEUED",
    "SuccessCount": 2,
    "code": "1000",
    "Results": [
        {
            "customerId": "1234568",
            "description": "QUEUED",
            "code": "1000"
        },
        {
            "customerId": "1234569",
            "description": "QUEUED",
            "code": "1000"
        }
    ],
    "transid": "435ce176-d0f4-450b-a32e-1bbf4f15a033"
}
{
    "FailureCount": 0,
    "TotalCount": 1,
    "description": "QUEUED",
    "SuccessCount": 1,
    "code": "1000",
    "Results": [
        {
            "customerId": "1234568",
            "description": "QUEUED",
            "code": "1000"
        }
    ],
    "transid": "435ce176-d0f4-450b-a32e-1bbf4f15a033"
}
Suggest Edits

Update App Profile

This API is used to update application profile of a customer.

 
puthttps://api.imiconnect.io/resources/v2/customerprofiles/<appid>/<appprofileKey>
 

Request

The update app profile request is specified as follows:

URI

https://api.imiconnect.io/resources/v2/customerprofiles/<appid>/<appprofileKey>

 
appid : Specifies the application id.
appprofilekey: Specifies the users application key. It will vary from application to application.

Method

PUT

Request Headers

The following table describes the request headers:

Request Header
Description

key

Client profile key

content-type

application/json

For data privacy and security reasons, the REST API is served over encrypted HTTPS. The standard HTTP is not supported.

Request Body

The following table describes the elements in the request body:

Parameter
Type
Mandatory
Description

attributes

Array of Strings

Yes

String of key/value pairs to update

Response Codes

This API may return the following response codes:

Response Code
Message
Description

1000

Queued

Returned when the request is queued.

7000

Invalid JSON

Returned when an invalid JSON request is sent.

7001

Authentication failed

Returned when an invalid service key or profile key is provided in the request.

7002

Service Key Missing

Returned when the parameter key is missing in the message request.

7003

Mandatory parameters missing

7006

Internal error occurred

Returned when an internal error occurs.

7010

Source IP is not whitelisted

Returned when a request is sent from an IP that is not whitelisted in IMIconnect.

7011

Invalid Attribute Value

Returned when an invalid value is provided for the customer or app profile Attributes object.

7018

Invalid app profile or app profile not linked to this client.

Returned when an application master profile does not exists.

Request Examples

{
    "Records": [{
        "customerId": "9876",
        "Attributes": {
            "verified": "1",
            "status": "1",
            "createdOn": "2016-07-11 17:02:51",
            "channel": "fb",
            "name": "Joe James1",
            "profile_pic": "https://fbcdn-profile-a.akamaihd.net/hprofile-ak-xfa1/v/t1.0-1/s200x200/10354686_10150004552801856_220367501106153455_n.jpg?oh=246adb8e3d7dc948f4d8025495fbf8dd&oe=57FD4150&__gda__=1476209436_66628acd9a55e42920bb3f0a823e1eac",
            "psid": "1223275837725015",
            "updatedOn": "2016-07-11 17:17:06"
        }
    }]
}
{
    "Records": [{
        "customerId": "9876",
        "Attributes": {
            "verified": "1",
            "status": "1",
            "channel": "twitter",
            "twitter_handle": "Vamsi_Rayudu",
            "twitter_name": "Vamsi_Rayudu1",
            "geolocation": "",
            "timezone": "",
            "twitterid": "755652926081761280",
            "createdOn": "2016-07-11 17:02:51",
            "updatedOn": "2016-07-11 17:17:06"
        }
    }]
}
{
    "Records": [{
        "customerId": "9876",
        "Attributes": {
            "verified": "1",
            "status": "1",
            "channel": "wechat",
            "nick": "vamsi punnam1",
            "language": "en",
            "wechat_user_id": "o8E7mwaZqY3Q9eaxeftj7TyD5EiE",
            "createdOn": "2016-07-11 17:02:51",
            "updatedOn": "2016-07-11 17:17:06"
        }
    }]
}
    {
        "Records": [{
            "customerId": "9876",
            "Attributes": {
                "verified": "0",
                "status": "1",
                "connectStatus": "1",
                "userId": "9876",
                "channel": "rt",
                "deviceId": "355004057394235",
                "rtmId": "9876_355004057394235",
                "make": "Apple",
                "model": "iPad 3(GSM)",
                "os": "ios",
                "osversion": "9.3.1",
                "pushId": "37bc5867465cb95124e5e03aad905100f8154cb4f1f5cb8c4a01eae8ee758316",
                "createdOn": "2016-07-11 17:02:51",
                "last_opened": "2016-07-25T16:39:54+0530",
                "last_upgraded": "2016-07-25T16:39:54+0530"
            }
        }]
    }

Response Example

{
    "FailureCount": 1,
    "TotalCount": 2,
    "description": "QUEUED",
    "SuccessCount": 1,
    "code": "1002",
    "Results": [
        {
            "customerId": "1234569",
            "description": "QUEUED",
            "code": "1000"
        },
        {
            "customerId": "2134",
            "description": "Customer not found",
            "code": "7203"
        }
    ],
    "transid": "b845127b-9b9c-4f4c-a1f6-ea6537afbf89"
}
Suggest Edits

Delete Profile

This API is used to delete a customer profile.

 
deletehttps://api.imiconnect.io/resources/v2/customerprofile/<customerid>
 

Cautionary Notice

This process is irreversible. Once a customer profile is deleted, it cannot be recovered. However, a new customer profile can be created with the same customer id.

Request

The delete profile request is specified as follows:

URL

https://api.imiconnect.io/resources/v2/customerprofile/<customerid>


customerid: A client specific ID (such as CRN) to uniquely identify a customer.

Method

DELETE

Request Headers

The following table describes the request headers:

Request Header
Description

key

Client profile key

content-type

application/json

For data privacy and security reasons, the REST API is served over encrypted HTTPS. Standard HTTP is not supported.

Response Codes

Following are the response codes this method may return:

Response Code
Message
Description

1000

Queued

Returned when the request is queued.

7001

Authentication failed

Returned when an invalid service key or profile key is provided in the request.

7002

Service Key Missing

Returned when the parameter key is missing in the message request.

7003

Mandatory parameters missing

7203

Customer not found

7208

Source IP is not whitelisted

Returned when a request is sent from an IP that is not whitelisted in IMIconnect.

Request Examples

https://api.imiconnect.com/resources/v1/customerprofile/1234
https://api.imiconnect.com/resources/v1/customerprofile?customerId=1234&customerId=1235

Response Examples

{
  "FailureCount": 0,
  "TotalCount": 1,
  "description": "QUEUED",
  "SuccessCount": 1,
  "code": "1000",
  "Results": [
    {
      "customerId": "1234",
      "description": "QUEUED",
      "code": "1000"
    }
  ],
  "transid": "b41b6aa3-8603-45d3-9c70-93dc384970e7"
}
{
  "FailureCount": 0,
  "TotalCount": 1,
  "description": "QUEUED",
  "SuccessCount": 1,
  "code": "1000",
  "Results": [
    {
      "customerId": "1234",
      "description": "QUEUED",
      "code": "1000"
    },
     {
      "customerId": "1235",
      "description": "QUEUED",
      "code": "1000"
    }
  ],
  "transid": "b41b6aa3-8603-45d3-9c70-93dc384970e7"
}
Suggest Edits

Delete App Profile

This API is used to delete application profile of a customer.

 
deletehttps://api.imiconnect.io/resources/v2/customerappprofile/<appid>/<customerid>
 

Cautionary Notice

This process is irreversible. Once a customer application profile is deleted, it cannot be recovered. However, customers can authenticate with the application and have it re-linked to their profile.

Request

The delete app profile request is specified as follows:

URL

https://api.imiconnect.io/resources/v2/customerappprofile/<appid>/<customerid>


appid: Specifies the application id.
customerid: Specifies the customer profile to be deleted.

Method

DELETE

Request Headers

The following table describes the request headers:

Request Header
Description

key

Client profile key

content-type

application/json

For data privacy and security reasons, the REST API is served over encrypted HTTPS. Standard HTTP is not supported.

Request Body

The following table describes the elements in the request body:

Parameter
Type
Mandatory
Description

appid

String

Yes

IMIconnect generated Channel application ID.

appprofilekey

String

Yes

Key for the profile.

Response Codes

Following are the response codes this method may return:

Response Code
Message
Description

1000

Queued

Returned when the request is queued.

7001

Authentication failed

Returned when an invalid service key or profile key is provided in the request.

7002

Service Key Missing

Returned when the parameter key is missing in the message request.

7003

Mandatory parameters missing

7010

Source IP is not whitelisted

Returned when a request is sent from an IP that is not whitelisted in IMIconnect.

7014

app profile not found

Request Examples

https://api.imiconnect.com/resources/v2/customerappprofile/a_635736738702976937/9876
https://api.imiconnect.com/resources/v2/customerappprofile/a_635736738702976937?customerId=9876&customerId=9877

Response Examples

{
    "FailureCount": 0,
    "TotalCount": 1,
    "description": "QUEUED",
    "SuccessCount": 1,
    "code": "1000",
    "Results": [{
        "customerId": "9876",
        "description": "QUEUED",
        "code": "1000"
    }],
    "transid": "e0de0ab3-9f99-4602-bf03-09916f8d6bcc"
}
{
    "FailureCount": 0,
    "TotalCount": 1,
    "description": "QUEUED",
    "SuccessCount": 1,
    "code": "1000",
    "Results": [{
        "customerId": "9876",
        "description": "QUEUED",
        "code": "1000"
    },
               {
        "customerId": "9877",
        "description": "QUEUED",
        "code": "1000"
    }],
    "transid": "e0de0ab3-9f99-4602-bf03-09916f8d6bcc"
}
Suggest Edits

Delete Device App Profile

This API is used to delete device profile from customer's application profile (there may be more than one device for a customer that are using the application).

 
deletehttps://api.imiconnect.io/resources/v2/customerappprofile/<appid>/<customerid>/<deviceid>
 

Cautionary Notice

This process is irreversible. Once a customer's device application profile is deleted, it cannot be recovered. However, customers can authenticate with the application using their customerid and have it re-linked to their profile.

Request

The delete app profile request is specified as follows:

URL

https://api.imiconnect.io/resources/v2/customerappprofile/<appid>/<customerid>/<deviceid>


appid: Specifies the application id.
customerid: Specifies the customer profile to which the device is associated.
deviceid: Specifies the device id to be deleted.

Method

DELETE

Request Headers

The following table describes the request headers:

Request Header
Description

key

Client profile key

content-type

application/json

For data privacy and security reasons, the REST API is served over encrypted HTTPS. Standard HTTP is not supported.

Request Body

The following table describes the elements in the request body:

Parameter
Type
Mandatory
Description

appid

String

Yes

IMIconnect generated Channel application ID.

customerid

String

Yes

Specifies the customer profile to which the device is associated.

deviceid

String

Yes

Specifies the device id to be deleted.

Response Codes

Following are the response codes this method may return:

Response Code
Message
Description

1000

Queued

Returned when the request is queued.

7001

Authentication failed

Returned when an invalid service key or profile key is provided in the request.

7002

Service Key Missing

Returned when the parameter key is missing in the message request.

7003

Mandatory parameters missing

7010

Source IP is not whitelisted

Returned when a request is sent from an IP that is not whitelisted in IMIconnect.

7014

app profile not found

Request Example

https://api.imiconnect.com/resources/v2/customerappprofile/a_635736738702976937/9876/4451830998765

Response Example

{
    "FailureCount": 0,
    "TotalCount": 1,
    "description": "QUEUED",
    "SuccessCount": 1,
    "code": "1000",
    "Results": [{
        "customerId": "9876",
        "description": "QUEUED",
        "code": "1000"
    }],
    "transid": "e0de0ab3-9f99-4602-bf03-09916f8d6bcc"
}

Suggest Edits

List Streams

Streams is used to route the messages from customers to one service. One stream per service limits users to hold conversations on multiple threads from the same service. So, a thread ID should be generated first, for every new thread title with a combination of message type, stream ID and thread title as shown in the below combination:
*<stream_id>_<message_type>_<thread_title>.

 
gethttps://rtm.imiconnect.io/rtmsAPI/api/v1/apps/$(appid)/streams
 

Request

The list stream request is specified as follows:

Request Headers

The following table describes the request headers:

Request Header
Description

secretKey

Secret key generated in backend application.

content-type

Application/JSON

Request Body

The following table describes the request parameters:

Parameter
Type
Mandatory
Description

appid

String

Yes

Specifies the application ID.

Request Body

The following table describes the elements in the request URL:

Parameter
Type
Mandatory
Description

appid

String

Yes

Specifies the app ID.

Response Example

{
  "status": "success",
  "streams": [
    {
      "id": "59197d9ee4b04a5c464d71f6",
      "created_on": "2017-05-15T10:06:22.848Z",
      "name": "APPUSERSTREAM"
    },
    {
      "id": "59267828e4b0479ee69708bb",
      "created_on": "2017-05-25T06:22:32.167Z",
      "name": "BOT"
    },
    ],
  "code": 0
}
Suggest Edits

App Threads

This API is used to fetch thread information from a given app.

 
gethttps://rtm.imiconnect.io/rtmsAPI/api/v1/apps/$(appid)/threads?start=0
 

Request

The app threads request is specified as follows:

Request Headers

The following table describes the request headers:

Request Header
Description

secretKey

Secret key generated in backend application.

content-type

Application/JSON

Request Body

The following table describes the request parameters:

Parameter
Type
Mandatory
Description

appid

String

Yes

Specifies the application ID.

start

Integer

No

Specifies the integer value where the record pointer should start in the app threads. A maximum of 100 threads can be returned (if available).

Request Body

The following table describes the elements in the request URL:

Parameter
Type
Mandatory
Description

appid

String

Yes

Specifies the application ID.

Request Example

{
  "total": 2,
  "count": 2,
  "threads": [
    {
      "id": "59197d9ee4b04a5c464d71f6_1_526e4c1265d503cf33676bf9343a2de75ebbf7fd",
      "title": "RTIRAPIEXPLORER",
      "created_on": "2017-05-22T07:27:12.218Z",
      "stream_name": "APPUSERSTREAM",
      "updated_on": "2017-05-22T07:27:12.218Z",
      "type": "announcement"
    },
    {
      "id": "59227838e4b000ec6d005d0f_0_cb9f444b8c3312fe3521421ab317fa3bb99a7c1c",
      "title": "chk2",
      "created_on": "2017-05-22T07:14:20.716Z",
      "stream_name": "Sprint122",
      "updated_on": "2017-05-22T07:14:20.716Z",
      "type": "Conversation"
    }
   ],
  "description": "success",
  "code": "0"
}
Suggest Edits

User Messages

This API is used to fetch thread message information for a specific threadId under a app and sync all the devices of a specific user.

 
gethttps://rtm.imiconnect.io/rtmsAPI/api/v1/apps/$(appid)/user/$(userid)/threads/$(threadid)/messages?from=<datetime>
 

Request

The app threads request is specified as follows:

Request Body

Parameter
Type
Mandatory
Description

appid

String

Yes

Specifies the application ID.

userid

String

Yes

Specifies the user ID.

threadid

String

Yes

g

from

String

No

To fetch thread message information in UTC format, until the specified date. A maximum of 100 messages can be fetched.

Request Headers

The following table describes the request headers:

Request Header
Description

secretKey

Secret key generated in backend application.

content-type

Application/JSON

Request Body

The following table describes the elements in the request URL:

Parameter
Type
Mandatory
Description

appid

String

Yes

Specifies the app ID.

userid

String

Yes

Specifies the user ID associated with the app.

Response Example

{
 "total" : 2,
 "count" : 2,
 "description" : "success",
 "code" : "0",
 "messages" : [{
   "status" : "read",
   "created_on" : "2017-09-01T11:39:55.257Z",
   "appid" : "BO25162038",
   "payload_type" : "sentToUser",
   "extras" : {
    "fb_psid" : "568021706655423"
   },
   "message" : "It is indeed!",
   "thread" : {
    "id" : "599ff158e4b0369b61ae54ef_0_7cf5a981af4ba80a9275509be45810c64f29bcaf",
    "title" : "437A9206D9B39116208019BA2A58C978",
    "stream_name" : "Foxtons"
   },
   "userId" : "A0D2FE5C5A7880E38FFE51D5B7CA531F",
   "read_at" : "2017-09-01T12:51:52.188Z",
   "delivered_at" : "",
   "tid" : "R82c051a7-dd27-43cc-875b-e86018cef033",
   "media" : []
  }, {
   "status" : "submited",
   "created_on" : "2017-09-01T11:39:43.858Z",
   "appid" : "BO25162038",
   "payload_type" : "sentByUser",
   "extras" : {
    "fb_psid" : "568021706655423"
   },
   "message" : "It's working!",
   "thread" : {
    "id" : "599ff158e4b0369b61ae54ef_0_7cf5a981af4ba80a9275509be45810c64f29bcaf",
    "title" : "437A9206D9B39116208019BA2A58C978",
    "stream_name" : "Foxtons"
   },
   "userId" : "A0D2FE5C5A7880E38FFE51D5B7CA531F",
   "read_at" : "",
   "delivered_at" : "",
   "tid" : "R47bda0cc-1b1c-4ae1-b164-df3442eddd87",
   "media" : []
  }
 ]
}
Suggest Edits

Create Thread

The in-app API is used to create a thread when a user wants to send MO. Gateway will return threadId as response.

 
posthttps://api.imiconnect.io/api/v1/apps/$(appid)/threads

Headers

secretKey
string
 

Request

The create thread request is specified as follows:

Request Headers

The following table describes the request headers:

Request Header
Description

secretKey

Secret key generated in backend application.

content-type

Application/JSON

Request Body

The following table describes the request parameters:

Parameter
Type
Mandatory
Description

appid

String

Yes

Specifies the application ID.

Request Example

{
   "externalid": "anything text or number",
   "type": "Conversation/Announcement",
   "title": "Sample title",
   "category": "Samplecategory",
   "extras": {
     					"Custom_Param1": "value1",
     					"Custom_Param2": "value1",
      				"Custom_Param3": "value1",
      				"Custom_Param4": "value1",
      				"Custom_Param10": ["value1","value2"]
   }
}

Request Body

The following table describes the elements in the request URL:

Parameter
Type
Mandatory
Description

externalid

String

No

Specifies the external ID

type

String

Yes

Specifies the type of thread. Conversation/Announcement

title

String

No

Specifies the thread title.

category

String

No

Specifies the thread category

extras

Numeric

No

Specifies custom parameters

Response Example

{
   "code": "0",
   "description": "success",
   "thread": {
      "id": "UUID",
      "created_on": "2017-05-03T13:14:37.985Z"
   }
}
Suggest Edits

User Threads

This API is used to fetch thread information from a given app.

 
gethttps://api.imiconnect.io/api/v1/apps/PO05125832/user/1723/threads?start=0
 

Request

The user threads request is specified as follows:

Request Headers

The following table describes the request headers:

Request Header
Description

secretKey

Secret key generated in backend application.

content-type

Application/JSON

Request Body

The following table describes the elements in the request URL:

Parameter
Type
Mandatory
Description

appid

String

Yes

App ID is an application specific ID, which is required to uniquely identify an application.

userid

String

Yes

Specifies the customer profile to which the device is associated.

start

Integer

No

Specifies the integer value where the record pointer should start in the app threads. A maximum of 100 threads can be returned (if available).

Response Example

{
   "code": "0",
   "description": "success",
   "count": "1",
   "total": "1",
   "threads": [
      {
         "id": "UUID",
         "type": "conversation",
         "externalid": "anything text or number",
         "status": "Active",
         "title": "Sample title",
         "category": "Samplecategory",
         "extras": {
            "Custom_Param1": "value1",
            "Custom_Param2": "value1",
            "Custom_Param3": "value1",
            "Custom_Param4": "value1",
            "Custom_Param10": [
               "value1",
               "value2"
            ]
         },
         "stream_name": "Umesh",
         "created_on": "2017-05-03T13:11:47.514Z",
         "updated_on": "2017-05-03T13:11:47.514Z"
      }
   ]
}
Suggest Edits

User Messages

This API is used to fetch thread message information for a specific threadId under a app and sync all the devices of a specific user.

 
gethttps://rtm.imiconnect.io/api/v1/apps/$(appid)/user/$(userid)/threads?start=0
 

Request

The app threads request is specified as follows:

Request Body

Parameter
Type
Mandatory
Description

appid

String

Yes

Specifies the application ID.

userid

String

Yes

Specifies the user ID.

start

Interger

No

Specifies the integer value where the record pointer should start in the app threads. A maximum of 100 threads can be returned (if available).

Request Headers

The following table describes the request headers:

Request Header
Description

secretKey

Secret key generated in backend application.

content-type

Application/JSON

Request Body

The following table describes the elements in the request URL:

Parameter
Type
Mandatory
Description

appid

String

Yes

Specifies the app ID.

userid

String

Yes

Specifies the user ID associated with the app.

Response Example

{
	"total": 1,
	"code": "0",
	"count": 1,
	"messages": [
		{
			"payload_type": "sentByUser",
			"extras": {},
			"media": [],
			"thread":{
			"id" : "UUID",
			"type": "conversation",
			"externalid": "anything text or number", //optional
			"status": "Active/Closed", //need clarification
			"title": "Sample title", //optional
			"category": "Samplecategory", //optional
			"extras": { //optional
												"Custom_Param1": "value1",
												"Custom_Param2": "value1",
												"Custom_Param3": "value1",
												"Custom_Param4": "value1",
												"Custom_Param10": ["value1","value2"]
								},
			"stream_name": "Umesh",
			"created_on" : "2017-05-03T13:11:47.514Z",
			"updated_on" : "2017-05-03T13:11:47.514Z",
		}
			"message": "Test2",
			"userId": "WwopGfVlcgKxbI2egTiT/Q==/Z8WPLM",
			"tid": "RDF5856B2-5197-4956-9809-CE68C9A446B9",
			"created_on": "2018-04-20T06:18:54.058Z",
			"appid": "R209113055",
			"read_at": "",
			"delivered_at": "",
			"status": "submited"
		}
	],
	"description": "success"
}
Suggest Edits

User Messages : Version 2

This API is used to fetch thread message information for a specific threadId under a app and sync all the devices of a specific user.

 
gethttps://rtm.imiconnect.io/api/v2/apps/$(appid)/user/$(userid)/threads?start=0
 

Request

The app threads request is specified as follows:

Request Body

Parameter
Type
Mandatory
Description

appid

String

Yes

Specifies the application ID.

userid

String

Yes

Specifies the user ID.

start

Interger

No

Specifies the integer value where the record pointer should start in the app threads. A maximum of 100 threads can be returned (if available).

Request Headers

The following table describes the request headers:

Request Header
Description

secretKey

Secret key generated in backend application.

content-type

Application/JSON

Request Body

The following table describes the elements in the request URL:

Parameter
Type
Mandatory
Description

appid

String

Yes

Specifies the app ID.

userid

String

Yes

Specifies the user ID associated with the app.

Response Example

{
	"total": 1,
	"code": "0",
	"count": 1,
	"messages": [
		{
			"payload_type": "sentByUser",
			"extras": {},
			"media": [],
			"thread":{
						"id": "5acb5fa7e4b04b585f09434d_0_f3f3cac48f810645875f97466b36993b522167ea"
				}
			"message": "Test2",
			"userId": "WwopGfVlcgKxbI2egTiT/Q==/Z8WPLM",
			"tid": "RDF5856B2-5197-4956-9809-CE68C9A446B9",
			"created_on": "2018-04-20T06:18:54.058Z",
			"appid": "R209113055",
			"read_at": "",
			"delivered_at": "",
			"status": "submited"
		}
	],
	"description": "success"
}
Suggest Edits

Update Thread

This API is used to update the thread information from a given app. Based on an app id, user id, and thread id, you can close or reopen a thread or update a thread information.

 
posthttps://api.imiconnect.io/api/v1/apps/$(appid)/user/$(userid)/threads/$(threadid)/update

Headers

secretKey
string
 

Request

The create thread request is specified as follows:

Request Headers

The following table describes the request headers:

Request Header
Description

secretKey

Secret key generated in backend application.

content-type

Application/JSON

Request Body

The following table describes the request parameters:

Parameter
Type
Mandatory
Description

appid

String

Yes

Specifies the application ID.

userid

String

Yes

Specifies the user ID.

threadid

String

Yes

Specifies the thread ID.

Request Example

Example Req 1:
{
“status”:”Closed” // This will change thread status to closed
}

Example Req 2:
{
“status”:”Active” // This will change thread status to active
}

Example Req 3:
{
“title” :”new_title” // This will change thread title to new value, Fields which are not updated remains same
}

 {
       “status”:”Closed” 
  }

Request Body

The following table describes the elements in the request URL:

Parameter
Type
Mandatory
Description

status

String

Yes

Specifies the update status

Response Example

{
  "code": "0",	
  "description": "success"
}
 

The transaction status API is used to query the status of the messaging API transaction carried out on a specific channel that was initiated through messaging API. Using this API you can retrieve message status and also know the status of the messages if failed due to any reason.

Following are the limitations of this API:

  • A message status can only be retrieved using a service key of the particular message transaction.
  • A message status can be requested within a month after the transaction is completed.
  • A message status can be retrieved only for Messaging MT API.
  • The transaction status API requests must be from whitelisted IPs at a client level.

For data privacy and security reasons, the REST API is served over encrypted HTTPS. Standard HTTP is not supported.

Name
Description

transactionid

Specifies the transaction id returned during the messaging request.

clientid

Specifies the client id in IMIconnect.

api_version

Specifies the Messaging API version.

type

Specifies the type of the API.

from

Specifies the originating point of the message.

  • SMS - Sender id or Short code
  • Voice - CLI number or Sender id.
  • RTM - Sender id

to

Specifies the destination point of the message.
For example,

  • SMS and Voice - MSISDN
  • Facebook - Facebook user id
  • RTM and Push - Customer id

body

Specifies the message sent.

channel

Specifies the channel through which the message was sent.

appid

Specifies the appid that is generated while creating an app.

status

Specifies the status of the message. The options are:

  • sent
  • queued
  • delivered
  • read
  • failed
  • expired
  • answered
  • rejected
  • busy
  • others
  • no answer
  • dropped

date_created

Specifies the date when the message was initiated.

last_updated

Specifies the last updated date of the transaction.

error_code

Specifies the error code when status of the message is not success.

error_message

Specifies the description of the error.

Response Codes

For information about status codes, click here.

Suggest Edits

Transaction Status

The transaction status API is used to query the status of a transaction carried out on a specific channel that was initiated through the messaging API.

 
gethttps://api.imiconnect.io/resources/v1/messaging/status/<TransactionID>
 

Request

The status of a transaction made through messaging API is requested as follows:

URL

https://api.imiconnect.io/resources/v1/messaging/status/<TransactionID>

 

Note: If your IMIconnect web access URL is on a .io TLD, then you should use the API end point with .io. For example, if your domain is mycompany.imiconnect.com then your API base URL will be api.imiconnect.com. But if your domain is mycompany.imiconnect.io then your API base URL will be api.imiconnect.io.
 


where
transactionid is the transaction ID returned during the messaging request.

Method

GET

Response Body

The parameters of response body are:

Name
Description

transactionid

Specifies the transaction ID returned during the messaging request.

clientid

Specifies the client ID in IMIconnect.

api_version

Specifies the Messaging API version.

type

Specifies the type of the API.

from

Specifies the originating point of the message.

  • SMS - Sender ID or Short code
  • Voice - CLI number or Sender ID.
  • RTM - Sender id

to

Specifies the destination point of the message.
For example,

  • SMS and Voice - MSISDN
  • Facebook - Facebook user ID
  • RTM and Push - Customer ID

body

Specifies the message sent.

channel

Specifies the channel through which the message was sent.

appid

Specifies the appid that is generated while creating an app.

status

Specifies the status of the message. The options are:

  • sent
  • queued
  • delivered
  • read
  • failed
  • expired
  • answered
  • rejected
  • busy
  • others
  • no answer

date_created

Specifies the date when the message was initiated.

last_updated

Specifies the last updated date of the transaction.

error_code

Specifies the error code when status of the message is not success.

error_message

Specifies the description of the error.

Status Codes

This API may return the following response codes:

Return Code
Message
Description

7000

Invalid JSON

Returned when an invalid JSON request is sent.

7001

Authentication failed

Returned when an invalid service key or profile key is provided in the request.

7002

Service Key Missing

Returned when the parameter key is missing in the message request.

7003

any one of [customerid,msisdn,email, userid,pushid,psid, twitterid, wechatid] is mandatory

Returned when a mandatory parameter is missing for destination.

7003

Mandatory parameters missing.

Returned when the mandatory parameters configured in custom event are missing.

7003

param 'text' is missing for android

Returned when parameter text or its value is missing for Android in push object.

7003

param 'text' is missing for ios

Returned when the parameter text or its value is missing for iOS in push object.

7003

param 'push' missing for push channel

Returned when the parameter push is missing.

7003

either android or ios information is mandatory for push channel

Returned when the push channel is missing in push object.

7003

param 'text' missing for channel fb

Returned when the parameter text or its value is missing for Facebook channel.

7003

param 'OTT-Messaging' missing for channel fb

Returned when the OTT-Messaging object is missing when deliverychannel is Facebook.

7003

param 'fb' missing for channel fb

Returned when the fb object is missing in OTT-Messaging object.

7003

param 'text' missing for channel wechat

Returned when the parameter text or its value is missing for WeChat channel.

7003

param 'wechat' missing for channel wechat

Returned when the wechat object is missing in OTT-Messaging object.

7003

param 'OTT-Messaging' missing for channel wechat

Returned when the OTT-Messaging object is missing when deliverychannel is WeChat.

7003

param 'text' missing for channel twitter

Returned when the parameter text or its value is missing for Twitter channel

7003

param 'twitter' missing for channel twitter

Returned when the parameter text or its value is missing for Twitter channel.

7003

param 'twitter' missing for channel twitter

Returned when the twitter object is missing in OTT-Messaging object.

7003

param 'OTT-Messaging' missing for channel twitter

Returned when the OTT-Messaging object is missing when deliverychannel is Twitter.

7003

param 'text' missing for channel rt

Returned when the parameter text or its value is missing for rt channel.

7003

param 'rt' missing for channel rt

Returned when the rt object is missing when deliverychannel is rt.

7003

param 'body' missing for channel sms

Returned when the parameter body or its value is missing for sms channel and the parameter type is not selected as text (1).

7003

param 'text' missing for channel sms

Returned when the parameter text or its value is missing for sms channel.

7003

param 'sms' missing for channel sms

Returned when the sms object is missing when deliverychannel is sms.

7003

either param 'callflowid' or param 'media' is required

Returned when the parameters callflowid or media or their values are missing for voice channel.

7003

param 'voice' missing for channel voice

Returned when the voice object is missing when deliverychannel is voice.

7003

No destination channel information found in request

Returned when the value is missing for deliverychannel.

7003

param 'deliverychannel' missing

Returned when the deliverychannel is missing.

7003

mandatory param device_types missing

Returned when device_types object is missing in interactive object.

7003

mandatory param value missing for action xxx

Returned when the parameter value is missing in actions array.

7003

mandatory param pos missing

Returned when the parameter pos is missing in actions array.

7003

mandatory param category missing

Returned when the parameter category is missing in interactive object.

7003

mandatory param actions missing

Returned when the parameter actions is missing in interactive object.

7004

invalid value for param 'priority', it should be one of [1,2,3,4,5]

Returned when the parameter priority value is other than 1 to 5 for rt channel.

7004

invalid value of param 'type' , only [1,2,3,4] are allowed

Returned when the parameter type value is other than 1 to 4 for sms channel.

7004

invalid delivery channel

Returned when the parameter delivery channel value is other than sms, voice, push, rt, fb, twitter or wechat.

7004

invalid device type xxx, only ios or android is allowed

Returned when the parameter device_types value is other than ios or android.

7004

duplicate device type xxx

Returned when duplicate position value is provided in device_types array in interactive object.

7004

invalid value of param pos, duplicate values for pos are not allowed

Returned when duplicate position value is provided in actions array in interactive object.

7004

invalid value of param action or action is invalid for this channel

Returned when an invalid action is provided in actions array in interactive object.

7004

invalid value of param value, specified value is invalid for action xxx

Returned when an invalid value is provided in value parameter in interactive actions object.

7004

invalid action for identifier xxx

Returned when an invalid action is provided for corresponding category.

7004

invalid identifier or no actions mapped for this identifier

Returned when the corresponding identifiers for category are not mapped to the identifiers that are there for actions.

7004

no identifier found for this category and at this position

Returned when identifiers are not found for a category.

7004

invalid value of param pos, only positions [xx,xx] are allowed for this category

Returned when an invalid position value is provided that is not there for corresponding category.

7004

invalid number of actions, expected actions size xx, but found xx

Returned when an unexpected number of actions found in interactive object.

7004

invalid value of param category or no identifiers mapped to this category

Returned when an invalid category is provided in request.

7005

Request expired

Returned when the request is expired.

7006

Internal error occurred

Returned when an internal error occurs.

7007

Service Inactive

Returned when a service is in inactive state.

7009

Maximum number of destination address

Returned when an API request exceeds the limit (1000) to send messages using messaging API.

7101

Invalid Sender ID

Returned when the sender ID is invalid.

7102

Invalid address

Returned when the address is invalid.

7103

Not enough credits

Returned when the client does not have enough credits in his account.

7104

Invalid app id

Returned when the app id is invalid.

7105

Customer profile not found

Returned w