Send an SMS
HTTP API sends a text message using POST and form-encoded data. The URL you use to send a text message has a required field called api_key, which is unique and assigned to your account.
The other required parameters for the Request are method, sender, to and message, which are used to define the destination phone number and the message body. If you want to send to multiple phone numbers, provide the numbers in comma separated format.
To send an SMS using the HTTP API, the following URL format is used:
curl -X POST \
'<BASE_URL>&method=sms&message=Test+sms&to=9172xxxxxxxx&sender=BRAND'
API Parameter Specifications
The API parameter specifications are described in the following sections.
Mandatory Parameters
The mandatory parameters in the HTTP API are tabulated below:
Parameter | Description | Expected Values |
---|---|---|
BASE_URL | BASE URL of your SMS Service | URL |
method | Predefined method | sms |
sender | Sender ID assigned to your account | Sender ID |
to | Receiver Mobile number to which SMS needs to be sent. It can be with or without 91. Also provide multiple numbers in comma separated format. | Mobile number (GET-10 numbers, POST-100 numbers) |
message | Message to be sent | Message text which is URL encoded (1000 char for normal, 500 for Unicode) |
Optional Parameters
The optional parameters in the HTTP API are tabulated below:
Parameter | Description | Expected Values |
---|---|---|
dlrurl | The encoded URL to receive delivery reports. Spiffing custom in the DLR url is mandatory. | delivery reports URL |
custom | Custom message ID by customer, comma separated | Alphanumeric (max 40 char) |
time | Date and time for scheduling an SMS | EX Format: YYYY-MM-DD HH:MM:SS OR YYYY-MM-DD HH:MM AM/PM |
unicode | To specify that the message to be sent is in unicode format. Also can be used for automatic detection of unicode SMS. | 1 / 0 / auto |
flash | To specify that the message is to be sent in the flash format | 1 or 0 |
Advanced Parameters(Optional)
The advanced parameters in the HTTP API are tabulated below:
Parameter | Description | Expected Values |
---|---|---|
format | Output format should be as specified by this variable | XML/JSON/JSONP. Default response will be in JSON |
callback | Callback function for JSONP response format | String |
custom1 & custom2 | Custom reference fields | Alphanumeric (max 40 char) |
port | Port number to which SMS has to be sent | Valid integer port number above 2000 |
Example Responses
- JSON
{
"status": "OK",
"data": [
{
"id": "811436f5-0053-4ea6-8cac-b035880b8473:1",
"customid": "1",
"customid1": "11",
"customid2": "22",
"mobile": "95XXXXXXXXX",
"status": "AWAITED-DLR"
},
{
"id": "811436f5-0053-4ea6-8cac-b035880b8473:2",
"customid": "2",
"customid1": "1",
"customid2": "2",
"mobile": "97XXXXXXXX",
"status": "AWAITED-DLR"
}
],
"message": "Campaign of 2 numbers Submitted successfully."
}
- XML
<?xml version="1.0" encoding="UTF-8" ?>
<api>
<status>OK</status>
<data>
<sms>
<id>e6bf8207-d226-4429-a1f0-ba0506efa539:1</id>
<customid>1</customid>
<customid1>11</customid1>
<customid2>22</customid2>
<mobile>95XXXXXXXX</mobile>
<status>AWAITED-DLR</status>
</sms>
<sms>
<id>e6bf8207-d226-4429-a1f0-ba0506efa539:2</id>
<customid>2</customid>
<customid1>1</customid1>
<customid2>2</customid2>
<mobile>99XXXXXXXX</mobile>
<status>AWAITED-DLR</status>
</sms>
</data>
<message>Campaign of 2 numbers Submitted successfully.</message>
</api>
Error Responses
{
"status":"A404",
"message": "Your api account got suspended"
}
Response Data
Parameter | Description |
---|---|
status | It indicates the success or failure of your request. |
message | It indicates the success or failure message. |
group_id | Website group id for your reference. Which is the current date |
data | All the response is wrapped in side data |
sms | Each number will be wrapped inside sms |
id | Website message id for your reference |
customid | Custom message id if you provide one |
customid1 | Custom message id 1 if you provide one |
customid2 | Custom message id 2 if you provide one |
mobile | Receiver Mobile number |
status | status of the message |
Send a Unicode SMS
Unicode SMS is basically a message which can be in regional language. In India, SMS can be sent in Tamil, Kannada, Hindi, English, etc type of languages. To send a unicode SMS using the HTTP API, the following URL format is used:
API Parameter Specifications
Additional API parameter specifications are described in the following sections.
curl -X POST \
'<BASE_URL>&method=sms&message=Test+sms&to=9172xxxxxxxx&sender=BRAND&unicode=1'
Mandatory Parameters
The mandatory parameters in the HTTP API are tabulated below:
Parameter | Description | Expected |
---|---|---|
unicode | To specify that the message to be sent is in unicode format. Also can be used for automatic detection of unicode SMS. | 1 / 0 / auto |
Schedule an SMS
This API can let user schedule SMS to single as well as multiple recipients at anytime. SMS cannot be scheduled before 5 minutes and after 3 months from the date of scheduling the SMS. To schedule an SMS using the HTTP API, the following URL format is used:
API Parameter Specifications
Additional API parameter specifications are described in the following sections.
curl -X POST \
'<BASE_URL>&method=sms&message=Test+sms&to=9172xxxxxxxx&sender=BRAND&time=dd%2Fmm%2Fyyyy%20hh%3Amm%20PM'
Mandatory Parameters
The mandatory parameters in the HTTP API are tabulated below:
Parameter | Description | Expected Values |
---|---|---|
time | Date and time for scheduling an SMS | EX Format: YYYY-MM-DD HH:MM:SS OR YYYY-MM-DD HH:MM AM/PM |
Sending a Port SMS
Using the below API, one can send a normal or unicode SMS to a particular port. Application port numbers can be used in SMS messages to deliver a particular SMS to an application on a mobile phone. If any application is present and running in that particular port, the text will be received as port SMS else the message will hit the native inbox of the mobile phone.
NOTE: The API tries to hit the application(port) for 10 seconds, if unsuccessful the message is delivered on the native inbox
To send a port SMS using the HTTP API, the following URL format is used:
API Parameter Specifications
The API parameter specifications are described in the following sections.
curl -X POST \
'<BASE_URL>&method=sms&message=Test+sms&to=9172xxxxxxxx&sender=BRAND&port=8xxx'
Mandatory Parameters
The mandatory parameters in the HTTP API are tabulated below:
Paramenters | Descriptions | Values |
---|---|---|
port | Port number to which SMS has to be sent | Valid integer port number above 2000 |