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

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

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