Karix SMS API
This guide provides specifications of the JSON based API connectivity provided by Karix (previously known as mGage India) to Acoustic customers so that they can send their transactional SMS messages quickly. Familiarity and experience with invoking the HTTP API request using JSON payload is necessary to use this API.
Note: This API can only be used by those Acoustic clients whose organizations have been set-up to send SMS’s using the Karix SMS gateway.
Features Supported By This API
These features are supported by this JSON API:
- One 2 One (single message to single recipient)
- One 2 Many (single message to multiple recipients)
Parameters supported by the JSON API call
| Parameter name | Description | Comments | JSON key | Is mandatory? | Possible views | Default value |
|---|---|---|---|---|---|---|
| API Version | To specify the version of this JSON API. | --- | ver | Yes | 1.0 | 1.0 |
| API Access Key | A unique key to identify the customer. | This will be generated by the Karix Provisioning team. IBM’s provisioning team will provide this to the customer. | key | Yes | XXX…X | N/A |
| Schedule Time | The schedule date and time for the message to be sent out. | String representing the date and time in the below format ‘yyyy-MM-dd HH:mm:ss’. Minimum schedule time is CurrentTime + 15 minutes. Maximum schedule time is CurrentDate + 3 months. Time is specified in India time zone. | sch_at | No | XXXXXX | null |
| MSISDN | To specify the mobile number(s). Mobile numbers must be specified in E.164 format. | The mobile numbers will be represented as JSON array. | dest | Yes | [“919620660000”, “919620660001”, “919620660002”] | N/A |
| Message Text | Message text to be sent out to mobile numbers. | Text up to 800 characters long. The long message text is contecated if supported by the mobile carrier and handsets. | text | Yes | XXX | N/A |
| From Address | To specify the Source (Sender) ID | Max Length is 15 | send | Yes | XXX | N/A |
| Content Type | Content type of the message | --- | type | No | PLAIN UNICODE | PLAIN |
| Send delivery notification | To specify about the Delivery Receipt (DLR) to be sent back or not. The DLR will be sent back in HTTP JSON API. | The client’s backend web server address will be provisioned as part of the account set-up. | dlr_reg | No | 1/0 | 0 |
| urltracking | To specify this message is having the URL tracked. | Allows the client to set-up shortened URLs that can be tracked using the Karix portal. The associated ID is embedded in the outgoing message text. | urltrack | No | 1/0 | 0 |
Note on Content Types
- By default, the API assume that the customer’s request is on UTF-8 charset. If you want to send in a different charset, then you have to specify the charset in the HTTP request’s content-type.
- The content type (type parameter) can be any one of the following:
PLAIN
UNICODE
Sample SMS JSON API
One 2 One (Single Message to Single Recipient)
This JSON API example refers specifically to the sending of a single message to a single recipient.
{
“ver”: “1.0”,
“key”: “xxxxxxxxxxxxx999xxxxx”,
“sch_at”: “yyyy-MM-dd HH:mm:ss”,
“messages”: [
{
“dest”: [“919620660000”],
“text”: “Sample Text 1”,
“send”: “Send 1”,
“type”: “Plain”,
“dlr_req”: “1”,
“urltrack”: “1”,
}
]
}
One 2 Many (Single Message to Multiple Recipients)
One 2 Many SMS is basically a type of group SMS in which same message is broadcasted to a large number of recipients.
This feature enables the user to send a single message content to the multiple mobile numbers. In this scenario, all the predetermined mobile numbers will receive the same format of message content.
The mobile numbers will be represented as JSON array [“mobile1”, “mobile2”, “mobile3”]. For example, [“919620660000”, “919620660001”]
This JSON API example refers specifically to the sending of a single message to mulitple recipients.
{
“ver”: “1.0”,
“key”: “xxxxxxxxxxxxx999xxxxx”,
“sch_at”: “yyyy-MM-dd HH:mm:ss”,
“messages”: [
{
“dest”: [“919620660000”, “919620660001”, “919620660002”],
“text”: “Sample Text 1”,
“send”: “Send 1”,
“type”: “Plain”,
“dlr_req”: “1”,
“urltrack”: “1”,
}
]
}
Response Format
Sample Success Response
{
“status”: {
“code”: “200”,
“desc”: “Request Accepted”
},
“ackid”: “23423412341234”,
“time”: “yyyy-MM-dd HH:mm:ss”
}
Sample Failure Response
{
“status”: {
“code”: “-106”,
“desc”: “Invalid credentials”
},
“ackid”: “N/A”,
“time”: “yyyy-MM-dd HH:mm:ss”
}
Status Codes for Responses
| Status code | Description | Comment |
|---|---|---|
| 200 | MSG_ACCEPTED | Request accepted |
| -999 | INTERNAL_ERROR | Internal error |
| -101 | API_VERSION_INVALID | Invalid API version |
| -102 | INVALID_JSON | Invalid JSON |
| -103 | IP_RESTRICTED | Invalid source IP |
| -104 | ACCOUNT_EXPIRED | Account expired |
| -105 | ACCOUNT_INACTIVATED | Account deactivated |
| -106 | ACCOUNT_INVALID_CREDENTIALS | Invalid username or password |
| -108 | SCHEDULE_OPTION_DISABLE | Scheduling feature disabled |
| -109 | SCHEDULE_INVALID_TIME | Invalid schedule time |
| -110 | SCHEDULE_TIME_BEYOND_TIME_BOUND | Schedule time is beyond the time bound |
| -111 | DESTINATION_EMPTY | Empty mobile number |
| -112 | DESTINATION_INVALID | Invalid mobile number |
| -113 | MESSAGE_EMPTY | Empty message content |
| -114 | INVALID_MSGTYPE | Invalid message type |
| -116 | DLRTYPE_INVALID | Invalid DLR type |
| -120 | URLTRACK_INVALID_OPTION | Invalid URL tracking option |
| -123 | TRAI_BLOCKOUT_TIME | Cannot send message in TRAI blockout time |
| -124 | SCHEDULE_TRAI_BLOCKOUT_TIME | Cannout schedule the message delivery time to TRAI blockout time |
Sample Format of Possible Error Responses
Internal error
Error code: -999
Description: This error response is thrown whenever an internal error occurs.
{
“status”: {
“code”: “-999”,
“desc”: “Internal Error”
},
“ackid”: “N/A”,
“time”: “yyyy-MM-dd HH:mm:ss”
}
Invalid API version
Error code: -101
Description: This error response is shown when the user entered an invalid API version.
{
“status”: {
“code”: “-101”,
“desc”: “Invalid API version”
},
“ackid”: “N/A”,
“time”: “yyyy-MM-dd HH:mm:ss”
}
Invalid JSON
Error doe: -102
Description: This error response is thrown when the JSON is Incomplete/not in proper JSON Format.
{
“status”: {
“code”: “-102”,
“desc”: “Invalid JSON”
},
“ackid”: “N/A”,
“time”: “yyyy-MM-dd HH:mm:ss”
}
Invalid source IP
Error code: -103
Description: This error response is thrown when the request from an unauthorized source.
{
“status”: {
“code”: “-103”,
“desc”: “Invalid source IP”
},
“ackid”: “N/A”,
“time”: “yyyy-MM-dd HH:mm:ss”
}
Account expired
Error code: -104
Description: This error response is thrown when the request is submitted from an expired account.
{
“status”: {
“code”: “-104”,
“desc”: “Account Expired”
},
“ackid”: “N/A”,
“time”: “yyyy-MM-dd HH:mm:ss”
}
Account deactivated
Error code: -105
Description: This error response is thrown when the request is submitted from a deactivated account.
{
“status”: {
“code”: “-105”,
“desc”: “Account Deactivated”
},
“ackid”: “N/A”,
“time”: “yyyy-MM-dd HH:mm:ss”
}
Invalid credentials
Error code: -106
Description: This error response is thrown when the username/password is incorrect.
{
“status”: {
“code”: “-106”,
“desc”: “Invalid credentials”
},
“ackid”: “N/A”,
“time”: “yyyy-MM-dd HH:mm:ss”
}
Scheduling feature disabled
Error code: -108
Description: This error response is thrown when the scheduling feature is disabled for that account.
{
“status”: {
“code”: “-108”,
“desc”: “Scheduling feature disabled “
},
“ackid”: “N/A”,
“time”: “yyyy-MM-dd HH:mm:ss”
}
Invalid schedule time
Error code: -109
Description: This error response is thrown when the schedule time in the request is not in the expected format.
{
“status”: {
“code”: “-109”,
“desc”: “Invalid schedule time”
},
“ackid”: “N/A”,
“time”: “yyyy-MM-dd HH:mm:ss”
}
Schedule time is beyond the time bound
Error code: -110
Description: This error response is thrown when the schedule time is beyond the time bound (i.e. beyond 3 months).
{
“status”: {
“code”: “-110”,
“desc”: “Schedule time is beyond the time bound”
},
“ackid”: “N/A”,
“time”: “yyyy-MM-dd HH:mm:ss”
}
Empty mobile number
Error code: -111
Description: This error response is thrown when the destination in the request is empty.
{
“status”: {
“code”: “-111”,
“desc”: “Empty mobile number”
},
“ackid”: “N/A”,
“time”: “yyyy-MM-dd HH:mm:ss”
}
Invalid mobile number
Error code: -112
Description: This error response is thrown when the destination number in the request is invalid.
{
“status”: {
“code”: “-112”,
“desc”: “Invalid mobile number”
},
“ackid”: “N/A”,
“time”: “yyyy-MM-dd HH:mm:ss”
}
Empty message content
Error code: -113
Description: This error response is thrown when the message content is empty in the request.
{
“status”: {
“code”: “-113”,
“desc”: “Empty message content”
},
“ackid”: “N/A”,
“time”: “yyyy-MM-dd HH:mm:ss”
}
Invalid message type
Error code: -114
Description: This error response is thrown when the message type is unsupported/invalid.
{
“status”: {
“code”: “-114”,
“desc”: “Invalid message type “
},
“ackid”: “N/A”,
“time”: “yyyy-MM-dd HH:mm:ss”
}
Invalid DLR type
Error code: -116
Description: This error response is thrown when the DLR type mentioned is invalid.
{
“status”: {
“code”: “-116”,
“desc”: “Invalid DLR type”
},
“ackid”: “N/A”,
“time”: “yyyy-MM-dd HH:mm:ss”
}
Invalid URL tracking option
Error code: -120
Description: This error response is thrown when the URL tracking option is invalid.
{
“status”: {
“code”: “-120”,
“desc”: “Invalid URL tracking option”
},
“ackid”: “N/A”,
“time”: “yyyy-MM-dd HH:mm:ss”
}
Cannot send message in TRAI blockout time
Error code: -123
Description: This error response is thrown when the customer has sent the messages at TRAI blockout time.
{
“status”: {
“code”: “-123”,
“desc”: “Cannot send the message in TRAI blockout time”
},
“ackid”: “N/A”,
“time”: “yyyy-MM-dd HH:mm:ss”
}
Cannot schedule the message delivery time to TRAI blockout time
Error code: -124
Description: This error response is thrown whenever the message delivery time is scheduled to TRAI blockout time.
{
“status”: {
“code”: “-124”,
“desc”: “Cannot Schedule the message delivery time to TRAI blockout time”
},
“ackid”: “N/A”,
“time”: “yyyy-MM-dd HH:mm:ss”
}
Updated over 1 year ago