Knowledgebase

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 alert, verification message or notifications SMS to its clients upon performing certain action, 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 request, success and erroneous responses.

Generate API Token

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

Left Navigation -> Integration -> API Token

Here is how it looks at first place before generating any API token. Click “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 API request.
Generate API Token

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 token to get authenticated.
Use API Token

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

API Token

Valid API Token is required to get authorization to submitting request

Values and Parameters 

API Endpoint 

'http://yourdomain.com/api'

Mobile No

Mobile number of the contact to whom the message will be sent  

Sender ID

Approved sender ID. If you don’t have any Sender ID approved or you don’t provide any sender ID as value of the Sender ID parameter, the message will be sent from the default sender ID of the gateway.

Message

Your short message text here. Make sure that the maximum length of one SMS is 160 characters, if the message text exceeds from 160 characters, an extra credit will be charged from your account. So every message consisting 160 characters is considered one text message, and crossing the 160 character limit will increase the message length from one message.

Sample Successful Request

Following sample API code illustrates that a request has been submitted to send “Test Message” using “HostingsH” as “Sender ID” to specific number in the number parameter. 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 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 success response upon send the above mentioned request.

Erroneous Responses

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

Upon submitting 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 Valid API Token and correct Parameters but wrong/invalid Mobile Number value like the following sample request with 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 reason of 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 certain number of words from getting relayed. Following is a sample request having a banned word within 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 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"}