API for Transactional SMS (Short Message Service)

Easily integrate the scalable REST API and programmatically use the sending gateway for transactional short messaging. The API is best suitable for the service providers/applications that need to send alerts, verification messages, or notifications SMS to their clients upon performing certain actions, i.e. Banks, Money Transfer Services, Mobile Wallets, etc. The API empowers such service providers to seamlessly interact with the sending gateway and send all of their alert, verification, and notification messages through the gateway. The following section describes using our transactional API with sample requests, success, and erroneous responses.

Generate API Token

Log into your account and generate your API token as the first step.

Left Navigation -> Integration -> API Token

Here is how it looks in the first place before generating any API token. Click the “Generate” button to generate your API token. The token doesn’t expire until you delete so you don’t need to generate a new token each time for sending an API request.

After you have generated the API token, two new buttons will appear on your screen, to “Copy” the API token that you have generated and to “Delete” your existing API token.  

1. Copy- Clicking on it will copy your existing API Token and will keep it in the clipboard until you paste it
2. Delete- It will delete the existing API token and will return to the earlier state where you will are required to generate a new token. The deleted tokens will automatically be considered as Expired or Inactivated that you will not be able to use anymore. The obvious consequence of deleting an existing API token is that you will have to generate a token to get authenticated.

Working with Transactional SMS API

The following section describes the formation of the API request that interacts with our gateway for sending transactional short messages and maintaining stats.

Required to Submit API Request

Values and Parameters 

Sample Successful Request

The following sample API code illustrates that a request has been submitted to send “Test Message” using “HostingsH” as “Sender ID” to a specific number in the number parameter. The following request uses the Curl function.

function sendMessage($sParam) {
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://yourdomain.com/api');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer 94d68306b4b67b035f00340493aefb00f3c5678b'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $sParam);
$result = curl_exec($ch);
if ($result === false) {
echo curl_error($ch);
}
curl_close($ch);
return $result;
}
$sParam = array(
'mobile_no' => '92333xxxxxxx',
'sender_id' => 'HostingsH',
'message' => 'Test Message'
);
echo $response = sendMessage($sParam); 

Successful Response

If you have inserted the Valid API Token that authorizes to submit the request, have used the correct Mobile Number and other parameters, the JSON based response will return.

Status value for the successfully executed request will be-
“sent”

Data Returned- "Message ID" and "Mobile Number" 

{"mobile_no":"92333xxxxxxx","message_id":"2b24bdfa-f846-4f43-9bbc-dd36630b4a49","status":"sent"}}

Following is the successful response upon sending the above-mentioned request.

Erroneous Responses

Following are few examples of erroneous responses upon submitting requests with inappropriate or invalid information. 

Upon submitting a request with wrong or invalid API token-{"Authorization":"failed”} 

When one of the parameters ('mobile_no' 'sender_id' or 'message') is wrongly used- {"error":"Invalid Parameters"}

When you submit a request with a Valid API Token and correct Parameters but wrong/invalid Mobile Number value like the following sample request with an invalid number.

function sendMessage($sParam) {
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://yourdomain.com/api');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer 94d68306b4b67b035f00340493aefb00f3c5678b'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $sParam);
$result = curl_exec($ch);
if ($result === false) {
echo curl_error($ch);
}
curl_close($ch);
return $result;
}
$sParam = array(
'mobile_no' => '92333873778544',
'sender_id' => 'HostingsH',
'message' => 'Test Message'
);
echo $response = sendMessage($sParam);

Status value for wrong/invalid Mobile Number value- "status":"failed” 

Data Returned-

Mobile Number

Text-based message describing the reason for mobile number failure

{"mobile_no":"929595acecesd","status":"failed","description":"Invalid Number String"}

Another reason of failure can be the use of one or more banned words within your text message. Our gateway blocks a certain number of words from getting relayed. Following is a sample request having a banned word within the message body.

function sendMessage($sParam) {
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'http://yourdomain.com/api');
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Authorization: Bearer 94d68306b4b67b035f00340493aefb00f3c5678b'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $sParam);
$result = curl_exec($ch);
if ($result === false) {
echo curl_error($ch);
}
curl_close($ch);
return $result;
}
$sParam = array(
'mobile_no' => '92333xxxxxxx',
'sender_id' => 'HostingsH',
'message' => 'Earn extra profit with this offer '
);
echo $response = sendMessage($sParam);

Status value after trying to send a request with one more banned words-"status":"failed” 

Data Returned-

Mobile Number

Text-based message providing banned word(s) that causes failure

{"mobile_no":"92333xxxxxxx","status":"failed","description":"Sending failed due to banned word","banned_words":"profit"}