This single API provides a multitude of functionality for multi-channel outbound messaging.
Headers
| Request Header | Description |
|---|---|
| key | Service Key |
| content-type | application/json |
{
"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
}
]
}
Response
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 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. |
[destination] | 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. |
[channels] | 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. |
[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:
If any invalid option or text is passed, then the priority is set as configured while creating the client. |
Channels
The channels parameter block configures channel communication parameters and will override the service's default values and the parameters in the base request.
Voice
The following parameters are part of the voice channel.
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 your regional support team for more info on setting up your own custom CLI. |