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