SMS API Routes

The SMS API provides several methods to perform the following tasks:

Outgoing SMS APIs

This API 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 can later be used to query the delivery report or receive delivery notification on the webhook URL.

The Send SMS API includes two routes - one for HTTP POST requests and the other for HTTP GET requests.

Send an 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"
}

Explanation of JSON Payload Keys

Object/KeyDescription
fromString. Optional. It is either a Sender-Id or a phone number (Short Code/Long Code).
template_idString. Required. ID of of the approved template. The template body will be used as the body of the SMS.
toArray of Strings. Optional. Either to or recipient is required. One or multiple recipient phone numbers. Optional
recipientArray of objects. Optional. It is a custom data structure of recipients used for data merging. to and recipient cannot be used together. If to is used, recipient is superseded. Note that each object in recipient must have a to key containing the recipient's phone number. uuid is used as an external-reference or a unique identifier provided to the SMS recipient.
dataObject. Optional. It contains custom data fields to use for one time data merging into the body of the template. The template with merged data fields is sent out to all the phone numbers. It works with to and not with recipient.
typeString. Enumerated values: sms, binary. The default is sms.
type_detailsHash. A hash with extra information. It is only used when a binary message is sent.
validityNumeric. Optional. Message validity in seconds. If a message is not delivered within this time, the message is discarded.
referenceString. Optional. Any external reference data that may be used.
data_codingString. Enumerated values: plain, unicode, auto.
flash_messageBoolean. Optional. The default value is false. Flash messages are shown on the screen without user interaction but the message is not saved in the inbox.
scheduled_atDatetime. Optional. Scheduled time of delivery in the RFC3339 format (Y-m-d\TH:i:s).
campaign_idString. Required. Campaign ID as configured through the EnableX portal.

Send an 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 a 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"
}

Explanation of Query String Parameters

Object/KeyDescription
fromString. Optional. It is either a Sender-Id or a Phone Number (Short Code/Long Code).
template_idString. Required. ID of an approved template. This template body will be used as the body of the SMS.
toOptional. Either to or recipient is required. One or multiple recipient phone numbers separated by comma. Note that phone numbers must be preceded with a + sign with an appropriate country code. When using it as a Query String, it needs to be url encoded, that is, use %2B instead of the + sign.
recipientOptional. 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 cannot be used together. If they are used together, recipient supersedes to. 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 a unique identifier provided to the recipient of the SMS. The object must have a key (with value) named against the each place holder in the template. Refer to the recipient array structure in the above JSON payload example.
dataOptional. Encoded value of a JSON object. It contains custom data for one time merging into the template body before sending it 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 above JSON payload example.
typeString. Enumerated values: sms, binary. The default is sms.
type_detailsHash. A hash with extra information. It is only used when a binary message is sent.
validityNumeric. Optional. Valididty of a message in seconds. If a message is not delivered within this time, the message is discarded.
referenceString. Optional. Any external reference data can be used.
data_codingString. Enumerated values: plain, unicode, auto.
flash_messageBoolean. Optional. The default value is false. Flash messages are shown on the screen without user interaction but the message is not saved in the inbox.
scheduled_atDatetime. Optional. Scheduled time of delivery. RFC3339 format (Y-m-d\TH:i:s)
campaign_idString. Required. Campaign ID as configured through the EnableX portal.

Get the SMS Delivery Status

This API route is used to obtain the delivery status of the SMS sending job posted to the EnableX SMS gateway given its "job_id". Note that if the Instant Delivery Notification webhook URL is configured, the delivery notifications are instantly posted to get real-time notification.

  • API Route: https://api.enablex.io/sms/v1/message/{job_id}
  • HTTP Request: GET
  • URL Format: job_id is appended to 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 is displayed only when it is provided in the recipients array of objects while sending an SMS.

Incoming SMS

To use the incoming SMS service, you need to have an incoming number and a webhook configured against your campaign. To configure your campaign, perform the following steps:

  1. Place an order for a phone number on the EnableX portal.
  2. Assign an incoming number to the campaign.
  3. Set up a webhook to receive notifications.

Place an Order for a Phone Number

To use the incoming SMS service, you need to configure a phone number against your campaign. You can place an order for a phone number (either Short Code or Long Code), choose a phone number from the EnableX Phone Inventory, or get a new phone number. For more information, see managing resources.

Assign an Incoming Number to a Campaign for Incoming SMS

You must set up a campaign and assign an incoming phone number to it to receive the incoming SMS. For an existing campaign, attach an incoming phone number to it.

To set up a campaign, follow the steps described in Create a Campaign.

To assign an incoming phone number to an existing campaign, go to the 'Edit Campaign' page of 'Campaign Settings' and perform the following steps:

  1. On 'My Dashboard', click 'SMS' in the 'My Projects' sidebar to navigate to the 'SMS Service' page.
  2. Click the Campaign Settings option and select your project name from the list of projects. Click Apply to confirm the project. Once you select a project, the list of campaigns created under the project are displayed.
  3. Click Edit to navigate to the 'Edit Campaign' page for the campaign. For setting up the campaign, see explanation of the options section Form Options.
  4. Select Sender Type to display the list of your existing local numbers. Click on the + icon to select a local number to link to the campaign.
  5. If you want to replace the local number linked with a campaign, click the - icon adjacant to the selected local number and repeat the last step to assign a new number to it.

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 have specified. The incoming message received on a number is forwarded to the Webhook URL using the HTTP POST method.

Webhook Settings

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

Incoming SMS API

An SMS is recieved in the following format on the configured webhook for further processing:

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

Explanation of JSON Payload Keys

Object/KeyDescription
idString. Required. Alphanumeric string to uniquely identify the message.
toNumeric. Required. Recipient phone number where the incoming message is received.
receivedDatetime. Required. Time in the UTC format when the message is received. Format (Y-m-d\TH:i:s).
fromNumeric. Required. Phone number of the sender who has sent the message.
bodyString. Body of the SMS.