Introduction
This User Manual provides specifications of the API for the automated sending of SMS via Internet and API. This guide is intended for the developers and clients alike who plan to integrate their systems with our SMS services.
Base URL for API Integration
Base URL will be defined as the common API URL parameters to be specified in every API trigger. All APIs shall contain this base URL.
https://thesmsbuddy.com/api/v1/
Check Account Balance
You can get the account balance of each service using this api.
https://thesmsbuddy.com/api/sms/balance/check
The following are the API Parameters
Parameter | Description | Expected Values |
---|---|---|
key | API/Working key generated from your SMS Account | Alphanumeric working key generated from web panel |
curl -X POST "https://thesmsbuddy.com/api/sms/balance/check" \
-d "key=XXXXXXXXXXXXXXXXXXXXXXXX"
Sample response
{
"status": "200",
"data": {
"trans": 100,
"promo": 0,
"transscrub": 50
}
}
Send SMS
The SMS API supports the following:
Note: As new DLT restrictions effective from Jan 31, we are suggesting to use the Template API for avoiding delivery issues related to DLT
POST - When you send a POST request with the end user’s phone number to the messaging subresource, We sends the SMS message you specify.
GET - You can retrieve the results of the message you sent using the GET method. You do this by sending a GET request containing the reference id for the message you sent.
We return a response message in the form of a JSON object in the entity body.
https://thesmsbuddy.com/api/v1/sms/send
Before you start sending transactional SMS through this API, please test whether your content is matching a template which has been pre approved. Otherwise, the SMS will end up being rejected.
The following are the API Parameters
Parameter | Description | Expected Values |
---|---|---|
key | API/Working key generated from your SMS Account | Alphanumeric working key generated from web panel |
type | Determines whether the SMS to be sent is Transactional, Promotional or other. | 1: Transactional 2: Promotional 3: Transscrub |
sender | The registered and approved Sender-id | Required |
to | Phone number to send with country prefix. (multiple numbers can be separated by comma.) | |
message | The content of the SMS | |
template_id | TemplateId registered in DLT portal (applicable for indian routes only) | |
schedule | Set whether message needs to schedule | 0: Normal message 1: Schedule message |
time | Schedule time at which the SMS has to be sent. | time in format i.e,yyyy-mm-dd hh:mm:ssxx` |
flash | This parameter can be used to send flash sms via API (Optional) | 0: Disable 1: Enable |
dlr_url | The URL you want to receive the status of the message. This URL can be accessed publicly. (Optional) | |
custom | The custom parameter you wants to receive on callback (Optional) |
curl -X POST "https://thesmsbuddy.com/api/sms/send" \
-d "key=XXXXXXXXXXXXXXXXXXXXXXXX" \
-d "type=1" \
-d "to=98xxxxxxxx" \
-d "sender=SMSBDY" \
-d "message=test message" \
-d "template_id=1234567890123456789"
Sample response
{
"status": "200",
"charges": 1,
"message": "1 numbers accepted for delivery.",
"data": [
{
"id": "4lso1rySHGz6cWfXVmwhD5hs-1",
"mobile": "9198xxxxxxxx",
"status": "AWAITING-DLR",
"unit": 1,
"length": 12,
"charge": 1
}
]
}
Send JSON SMS
You can send sms using POST method content in body.
All params in send sms will support in JSON also.
https://thesmsbuddy.com/api/v1/sms/send/json
root entry holds the default values for each node. You can overwite the root message values inside nodes value
Example Body{
"root":{
"type":"1",
"flash":"0",
"sender":"XXXXXX",
"message":"common test message",
"key":"XHXdxxxxxxxxxxxxxxxxUci",
"template_id":"XHXdxxxxxxxxxxxxxxxxUci",
},
"nodes":[
{
"to":"98xxxxxxxx",
"message":"test message 1",
"refid":"2"
},
{
"to":"98xxxxxxxx"
}
]
}
The following are the root parameters
Parameter | Description | Expected Values |
---|---|---|
key | API/Working key generated from your SMS Account | Alphanumeric working key generated from web panel |
type | Determines whether the SMS to be sent is Transactional, Promotional or other. | 1: Transactional 2: Promotional 3: Transscrub |
sender | The registered and approved Sender-id | Required |
message | The content of the SMS | |
template_id | TemplateId registered in DLT portal (applicable for indian routes only) | |
flash | This parameter can be used to send flash sms via API (Optional) | 0: Disable 1: Enable |
dlr_url | The URL you want to receive the status of the message. This URL can be accessed publicly. (Optional) |
The following are the node parameters
Parameter | Description | Expected Values |
---|---|---|
to | Recipient's MSISDN | Required |
message | The content of the SMS | Optional. Will override root message |
refid | Reference parameter | Optional |
curl --request POST \
--url https://thesmsbuddy.com/api/v1/sms/send/json \
-H 'Content-Type: application/json' \
--data '{
"root":{
"type":"1",
"flash":"0",
"sender":"XXXXXX",
"message":"common test message",
"key":"XHXdxxxxxxxxxxxxxxxxUci",
"template_id":"XHXdxxxxxxxxxxxxxxxxUci",
},
"nodes":[
{
"to":"98xxxxxxxx",
"message":"test message 1",
"refid":"2"
},
{
"to":"98xxxxxxxx"
}
]
}'
Sample response
{
"status": "200",
"charges": 2,
"message": "2 numbers accepted for delivery.",
"data": [
{
"id": "sMsq7YOOrYqRMibQlX1zKJJd-1",
"mobile": "9198xxxxxxxx",
"status": "AWAITING-DLR",
"unit": 1,
"length": 14,
"charge": 1,
"refid": 2
},
{
"id": "sMsq7YOOrYqRMibQlX1zKJJd-2",
"mobile": "9198xxxxxxxx",
"status": "AWAITING-DLR",
"unit": 1,
"length": 19,
"charge": 1,
"refid": ""
}
]
}
Send OTP SMS
The SMS API supports the following:
Note: As new DLT restrictions effective from Jan 31, we are suggesting to use the Template API for avoiding delivery issues related to DLT
POST - When you send a POST request with the end user’s phone number to the messaging subresource, We sends the SMS message you specify.
GET - You can retrieve the results of the message you sent using the GET method. You do this by sending a GET request containing the reference id for the message you sent.
We return a response message in the form of a JSON object in the entity body.
https://thesmsbuddy.com/api/v1/otp/create
Before you start sending transactional SMS through this API, please test whether your content is matching a template which has been pre approved. Otherwise, the SMS will end up being rejected.
The following are the API Parameters
Parameter | Description | Expected Values |
---|---|---|
key | API/Working key generated from your SMS Account | Alphanumeric working key generated from web panel |
sender | The registered and approved Sender-id | Required |
to | Phone number to send with country prefix. | Required |
message | The content of the SMS. OTP variable need to set as {#otp#}. (Example: Your Verification code is {#otp#}.) | |
template_id | TemplateId registered in DLT portal (applicable for indian routes only) | |
otp | OTP to send and verify. If not sent, OTP will be generated. | |
expiry | Expiry of OTP to verify, in minutes | default : 2 hours min : 1 minute, max : 1 Day |
digits | Number of digits in OTP | default : 6 min : 4, max : 10 |
curl -X POST "https://thesmsbuddy.com/api/otp/create" \
-d "key=XXXXXXXXXXXXXXXXXXXXXXXX" \
-d "to=98xxxxxxxx" \
-d "sender=SMSBDY" \
-d "message=Your Verification code is {#otp#}." \
-d "template_id=1234567890123456789"
Sample response
{
"status":"200",
"message":"OTP Generated Successfully",
"otp":{
"mobile":"9198xxxxxxxx",
"status":"PENDING",
"otp":"1234",
"expiry":"2022-03-09 07:38:06"
},
"sms":{
"id":"N8yB47bNaR5sfIlbnATKCZyE-1",
"mobile":"9198xxxxxxxx",
"status":"AWAITING-DLR",
"unit":1,
"length":33,
"charge":1
}
}
Verify OTP
https://thesmsbuddy.com/api/v1/otp/verify
The following are the API Parameters
Parameter | Description | Expected Values |
---|---|---|
key | API/Working key generated from your SMS Account | Alphanumeric working key generated from web panel |
to | Phone number to send with country prefix. | Required |
otp | OTP to verify. |
curl -X POST "https://thesmsbuddy.com/api/otp/verify" \
-d "key=XXXXXXXXXXXXXXXXXXXXXXXX" \
-d "to=98xxxxxxxx" \
-d "otp=123456"
Sample response
{
"status":"200",
"message":"OTP Verified Successfully"
}
Create Sender ID
The Sender ID creation API supports the following:
https://thesmsbuddy.com/api/v1/senderid/create
The following are the API Parameters
Parameter | Description | Expected Values |
---|---|---|
key | API/Working key generated from your SMS Account | Alphanumeric working key generated from web panel |
senderid | New Sender ID | Required |
description | Description for the sender | Optional |
pe_id | PE ID value (applicable for indian routes only) | Optional |
header_id | Header ID value (applicable for indian routes only) | Optional |
curl -X POST "https://thesmsbuddy.com/api/senderid/create" \
-d "key=XXXXXXXXXXXXXXXXXXXXXXXX" \
-d "senderid=SMSBDY" \
-d "description=my sender id description" \
-d "pe_id=XXXXXXXXXX" \
-d "header_id=XXXXXXXXXXX"
Sample response
{
"status": "200",
"message": "Sender ID requested Successfully."
}
Error Codes
You can get the account balance of each service using this api.
Error Code | Description |
---|---|
200 | Success Response |
400 | Incomplete request - Any one of mandatory field missing |
422 | Invalid Service Type |
401 | Invalid API Key |
412 | Invalid Sender ID |
451 | Sorry, this service is allowed only between 10AM & 9PM - Monday to Sunday. Request you to kindly try scheduling the campaign during the said timings. Thank you. |
406 | No Valid Numbers |
416 | Service Not Available |
409 | Insufficient Balance |
429 | Too many requests received. Your threshold value is 1000 SMS/minute. Please contact support. |
500 | There is an issue at our end. Please submit your request again. |