Karix SMS JSON API user guide

Overview

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

Description

Comments

JSON Key

Mandatory

Possible values

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. Acoustic's provisioning team will provide this to the customer

key

Yes

XXX...X

Not applicable

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

MSIDSN

To specify the mobile number(s). Mobile numbers must be specified in E.164 format.

The mobile numbers will be represented as JSON array.

For example, ["919620660000", "919620660001", “919620660002”]

dest

Yes

["919620660000", "919620660001", "919620660002"]

Not applicable

Message text

Message text to be sent out to mobile numbers

Text up to 800 characters long. The long message text is concatenated if supported by the mobile carrier and handsets.

text

Yes

XXX

Not applicable

From address

To specify the Source (Sender) ID.

Maximum length is 15.

send

Yes

XXX

Not applicable

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

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.

url track

No

1/0

0

Note on content types:

  1. 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.
  2. The content typle (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

Status 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

DESTINATION_EMPTY

Empty mobile number

-110

SCHEDULE_TIME_BEYOND_TIME_BOUND

Invalid mobile number

-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

Cannot 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 code: -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 unauthorized source.

{

  "status": {

    "code": "-103",

    "desc": "Invalid source IP"

  },

  "ackid": "N/A",

  "time": "yyyy-MM-dd HH:mm:ss"

}

**Account expired
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"

}

Did this page help you?