Table of Contents
How to use SMS API?
SMS API Host URL
SMS API Host: https://api.enablex.io/sms/
Every major version release of API will have a sub-directory named after major version number. This is known as Base URL for a SMS API Version, e.g.
Version Base URL: https://api.enablex.io/sms/v1/
All SMS API Routes are mapped to the Version Base URL, e.g.
Message Route: https://api.enablex.io/sms/v1/messages/
API Authentication
The SMS API uses HTTP Basic Authentication mechanism to authenticate API calls. Each API call is validated via the authentication header.
The following Information is used as credentials to access SMS API for your Application in the HTTP basic authentication header in the API call request
- Application ID or APP_ID as Username
- Application Key or APP_KEY as Password
POST https://api.enablex.io/sms/v1/messages/ Authorization: Basic XXXXXXX Content-Type: application/json
The Authorization header in the above example contains a value XXXXX which is a base64 encoded string of the APP_ID:APP_KEY.
How to get APP_ID & APP_KEY
All API Credentials are paired to a Project. You will need to create a Project first to receive the API credentials. To create Project, follow the given steps:
- Login to EnableX Portal
- Navigate: {Main Menu} Projects / My Projects
- Click: Project Name – to reach Project Dashboard. Access Credentials for the Project can be found here.
API Responses
The SMS API call make use of JSON Result Code to determine if the API call is successful.
Success Response
Successful API calls will always return JSON with a 0 (zero) Result Code.
{ "result": 0, …. …. }
Error Response
If unsuccessful for whatever reason the API will return a JSON with a non—zero result code. An error response in JSON will always carry 3 keys, viz. result code, error, description. See example below:
{ "result": "Non-Zero Result Code", "error": "Short reason", "desc": "Descriptive information about the error / warning" }
Result Code Grouping
The Result Codes of API are grouped into 5 categories as shown in the table below:
Code | Category | Description |
1xx | Information | Request received & processed |
2xx | Success | Request received & accepted |
3xx | Redirection | Action required to complete Request |
4xx | Client Error | Illegible Request Syntax. Can’t be fulfilled |
5xx | Server Error | Failed to complete a legit Request |
Outgoing SMS APIs
Send SMS
This Route is used to send promotional and transactional SMS either individually or in bulk. If the request to send SMS is accepted, the API returns a “job_id” for the accepted Job. The Job ID may later be used to query delivery report or receive delivery notification on Web Hook URL.
- API Route: https://api.enablex.io/sms/v1/messages/
- HTTP Request: POST
Request Example
POST https://api.enablex.io/sms/v1/messages/ Authorization: Basic XXXXXXX Content-Type: application/json { “from”: “+44xxxxxxxx”, “body”: “{$name} you are due to pay Rs. {$amount}”, “direct”: true, “recipient”: [ { “to”: “+91xxxxxx”, “name”: “Kamal”, “amount”: “30”, "body": "This body supercedes with direct: true", "uuid": "String" } ], “type”: “sms”, “reference”: “XOXO”, “validity”: “30”, “type_details”: “”, “data_coding”: “plain”, “flash_message”: false, “scheduled_dt”: “2019-12-17T14:26:57+00:00”, “created_dt”: “2019-12-15T14:26:57+00:00”, “campaign_id”: “XX”, “template_id”: “37081401” }
Response Example
{ “result”: 0, “job_id”: “5e71f1b23630865c34443fb4” }
JSON Payload – Key Explanation
Object / Key | Description |
from | String. Optional. Its either a Sender-Id or a Phone Number (Short Code / Long Code) |
body | String. SMS Body |
template_id | String. Optional. ID of of approved Template. body and template_id may not be used together. If used template_id supersedes.[K10] |
direct | Boolean. Optional. If set to true, you can use body in recipient in each object. So, body given against each recipient will overwrite global body explained above. |
to | Array of Strings. One or many Recipient Phone Number |
recipient | Array of Objects. Custom Data Structure of Recipient used for data merging. to and recipient may not be used together. If used recipient supersedes. Note that each object in recipient must have a to key containing the Recipient’s Phone Number. uuid is used as external-reference or Unique Identifier given to the SMS Recipient. Also, if you use body key here with diretct:true , it will overwrite body defined outside. |
type | String. Enumerated values: sms, binary. Default: sms |
type_details | Hash. A hash with extra information. Is only used when a binary message is sent. |
validity | Numeric. Optional. In Seconds that the message is valid. If a message is not delivered within this time, the message will be discarded. |
reference | String. Optional. Any external reference data may be used |
data_coding | String. Enumerated values: plain, unicode, auto |
flash_message | Boolean. Optional. Default false. Flash messages are shown on screen without user interaction while not saving the message to the inbox. |
scheduled_at | Datetime. Optional. Scheduled time of delivery. RFC3339 format (Y-m-d\TH:i:s) |
campaign_id | String. Required. Campaign ID as setup through EnableX Portal. |
Get Delivery Status
This Route is used to get delivery status of SMS Sending Job posted to EnableX SMS Gateway given it’s “job_id”. Note that if Instant Delivery Notification Web Hook URL is configured, the delivery notifications are posted instantly to get real time notification.
- API Route: https://api.enablex.io/sms/v1/message/{job_id}
- HTTP Request: GET
Note the “job_id” is appended in the URL.
Request Example
GET https://api.enablex.io/sms/v1/message/5e71f1b23630865c34443fb4 Authorization: Basic XXXXXXX Content-Type: application/json
Response Example
{ “result”: 0, “job_id”: “5e71f1b23630865c34443fb4”, “summary”: { “total”: 10, “sent”: 10, “delivered”: 8, “failed”: 1, “unknown”: 1 }, "detailed":[{ "to":"+99999999999", "sent":"2020-10-16UTC08:29:42", "delivered":"2020-10-1613:59:43", "uuid":"1268999", "status":"delivered" } ] }
Note: detailed[n].uuid
appears only when its given in the recipients
Array of Objects while sending SMS