How to use SMS API?
Outgoing SMS API Route
- Send SMS
- Get Deliver Status
Delivery Notifications
Incoming SMS API Route

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.

The Send SMS API has 2 different routes, one for HTTP POST Request and the other one for HTTP GET Request.

Send SMS Using HTTP POST Method

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": "+44999999999",
       "to": [ "+91999999999",  "+91888888888" ]
       "recipient": [    
            {
                "to": "+91999999999",
                "name": "Kamal",
                "amount": "30",
		"uuid": "String"
            }
        ],
       "data":   {
                "event": "Arts & Crafts Fair",
                "venue": "Dilli Hat",
                "start_date": "Mar 26, 2023",
		"end_date": "Mar 31, 2023" 
        },
       "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)
`template_id`	String. Required. ID of of approved Template. Template body will be used as SMS body.
`to`	Array of Strings. Optional. Either `to` or `recipient` is required. One or many Recipient Phone Number. Optiona
`recipient`	Array of Objects. Optional. It is a Custom Data Structure of Recipients 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.
`data`	Object. Optional. It contains custom data fields to used for one time data merging into the Template’s Body and the merged body is sent out to all phone numbers. It works with `to` and not with `recipient`.
`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.

Send SMS Using HTTP GET Method

API Route: https://api.enablex.io/sms/v1/send-sms/
HTTP Request: GET

Request Example#1 Programmable HTTP Request

GET https://api.enablex.io/sms/v1/send-sms

username=XOXO&password=XOXO&from=+44999999999&to=+91999999999,+91888888888&type=sms&reference=XOXO&data_coding=plain&campaign_id=XOXO&template_id=XOXO

Request Example#2 Using Direct URL with Query String

https://api.enablex.io/sms/v1/send-sms?username=XOXO&password=XOXO&from=+44999999999&to=+91999999999,+91888888888&type=sms&reference=XOXO&data_coding=plain&campaign_id=XOXO&template_id=XOXO

Response Example

{      “result”: 0,
       “job_id”:  “5e71f1b23630865c34443fb4”
}

Query String Parameter Explanation

Object / Key	Description
`from`	String. Optional. Its either a Sender-Id or a Phone Number (Short Code / Long Code)
`template_id`	String. Required. ID of of approved Template. Template body will be used as SMS body.
`to`	Optional. Either `to` or `recipient` is required. One or many Recipient Phone Numbers separated by comma. Note, phone number needs to leading + sign with country code. While using as Query String, it needs to be url encoded. i.e. %2B to be used instead of + sign
`recipient`	Optional. URL Encoded value of a JSON Structure for Array of Objects. It is a Custom Data Structure of Recipients used for data merging. `to` and `recipient` may not be used together. If used `recipient` supersedes. Note that each object in the Array 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. The Object must have a key (With value) named against the each place holder in the Template. Refer the `recipient` array structure in the JSON Payload example given above in the document
`data`	Optional. Encoded value of a JSON Object. It contains custom data for one time merging into the template body before sending out to all. It works with `to` and not with `recipient`. The Object must have a key (With value) named against the each place holder in the Template. Refer the `data` object structure in the JSON Payload example given above in the document
`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: For delivered & failed message

{
  "result": 0,
  "job_id": "5e71f1b23630865c34443fb4",
  "summary": {
    "total": 2,
    "sent": 0,
    "delivered": 1,
    "failed": 1,
    "unknown": 0
  },
  "detailed": [
    {
      "to": "+99999999999",
      "sent": "2020-10-16 08:29:42",
      "delivered": "2020-10-16 13:59:43",
      "uuid": "1268999",
      "status": "delivered"
    },
    {
      "to": "+99999999999",
      "sent": "2020-10-16 08:29:42",
      "uuid": "1268999",
      "error_code": "202",
      "error_des": "User abort",
      "status": "failed"
    }
  ]
}

Note:

detailed[n].uuid appears only when its given in the recipients Array of Objects while sending SMS.
status: Enuemrated data: sent, delivered, failed, unknown.
error_code & error_des: These are available for known failure reasons.

SMS Delivery Notifications

You may receive instant SMS Delivery notifications using a Webhook configuration against your Campaign. A status update in JSON will be posted to your Webhook as Raw Body when a message is delivered or failed to delivery.

{
  "job_id": "5e71f1b23630865c34443fb4",
  "detailed": [
    {
      "to": "+99999999999",
      "datetime": "2020-10-16 08:29:42",
      "status": "delivered"
    },
    {
      "to": "+99999999999",
      "datetime": "2020-10-16 08:29:42",
      "error_code": "202",
      "error_des": "User abort",
      "status": "failed"
    }
  ]
}

Note:

status: Enumerated data: sent, delivered, failed, unknown.
error_code & error_des: These are available for known failure reasons.

Incoming SMS APIs

Using Incoming SMS Service requires having an Incoming Number and Webhook configuration against your Campaign. Follow the steps below to configure your Campaign:

Place an order for a Phone Number
Assign Incoming Number to the Campaign
Set up your Webhook to receive notifications

Place an order for a Phone Number

To use Incoming SMS Service, you need to get a Phone Number to be configured against your Campaign. You need to place an order for a Phone Number (either Short Code or Long Code). You may opt either to choose one from EnableX Phone Inventory or get a new one. [Read More…]

Assign Incoming Number to the Campaign for Incoming SMS

Set up a campaign and assign the Incoming Number to receive the Incoming SMS. If you have an existing Campaign, attach the Incoming Number to the Campaign.

To setup a campaign, follow the steps as explained in the Create Campaign section.

To assign the Incoming Number to an existing campaign, go to the ‘Edit Campaign’ page of the ‘Campaign Settings’ and follow these steps:

On ‘My Dashboard’, click ‘SMS’ in the ‘My Projects’ sidebar to reach the SMS Service page.
Click the Campaign Settings option and select the Project Name from the list. Click ‘Apply’ to confirm the project. Once you select a project, it displays the list of Campaigns created under this project.
Click the ‘Edit’ icon to navigate to the ‘Edit Campaign’ page for the Campaign. Refer to the Explanation of the Form Elements section for more details on setting up the Campaign.
As you select the ‘Sender Type’, it displays the list of your existing Local Numbers. Click on the ‘+’ icon to select an existing Local Numbers to link to this campaign.
In case you want to replace the linked local number to a campaign, click the ‘-‘ icon in front of the selected Local Number and repeat the previous step to assign a new number.

Set up your Webhook

When a message arrives at your Enablex phone number, Enablex sends a request to your web application just like a web browser using the Webhook URL that you’ve specified. Incoming message received on a number is forwarded to the Webhook URL using the HTTP Post.

Webhook Settings

Enter the Webhook URL and save it to set up your Webhook to receive notifications for incoming SMS.

Receive SMS

Below is the format of received SMS on the configured Webhook for further processing.

Incoming SMS Format

{
"id":"61e8efab5c8ece74657d3d54",
"to":"919072670220",
"received":"2022-01-20T05:14:19Z",
"from":"919560098163",
"body":"Hello"
}