Bulk SMS Http API Specification



LekkiHost – Bulk SMS Http API Specification

(Document Version 1.0.0)

 

(This Document gives details on how to send messages via the Bulk HTTP API for the SMPP System)

           

HTTP API to submit messages on SMPP :

 

http://<server>:<port>/bulksms/bulksms?username=XXXX&password=YYYYY&type=Y&dlr=Z&destination=QQQQQQQQQ&sour ce=RRRR&message=SSSSSSSS<&url=KKKK>

<server>:XXX.XXX.XXX.XXX

<port>:8080

Parameters are explained below, please note that all the parameters (especially message and url) should be URL-UTF-8 encoded.

 

username: Username of the SMPP Account

password: Password of the SMPP Account

 

type: Indicates the type of message.

Values for "type":-

0: Plain Text (GSM 3.38 Character encoding)

1: Flash Message (GSM 3.38 Character encoding)

2: Unicode

3: Reserved

4: WAP Push

5: Plain Text (ISO-8859-1 Character encoding)

6: Unicode Flash

7: Flash Message (ISO-8859-1 Character encoding)

 

dlr: Indicates whether the client wants delivery report for this message

Range of values for "dlr":-

0: No Delivery report required

1: Delivery report required

 

destination: Mobile Number to which to Send message to (may or may not include a ‘+’ sign), multiple mobile numbers can be separated by commas (note the comma (',') should be URL encoded).

 

source: The source address that should appear in the message

Max Length of 18 if Only Numeric

Max Length of 11 if Alpha numeric

If you wish plus ('+') should be prefixed to the sender address when the message is displayed  on the cell phone, please prefix the plus sign to your sender address while submitting the message (note the plus sign should be URL encoded). Additional restrictions on this field may be enforced by the SMSC.

 

message: The message to send (Can be used for 'long' messages, that is, messages longer than 160 characters for plain text, 140 for flash and 280 for Unicode)For concatenated (long) messages we will be counting as one message for every 153 characters for plain text and 268 characters for Unicode, as the rest of the characters will be used by the system for packing extra information for re-assembling the message on the cell phone. In case of WAP Push  (type = 4), this is the text that would appear in the message. Also in the latter case, to send  non-English characters in the message, you only have to directly URL encode them  (using UTF-8 character encoding scheme).

 

url: If sending a WAP Push message (type=4), this holds the link that you wish to send, for any other type of message, no value needs to be supplied for this field (if specified will be ignored) . Just like “message” field, this field should also be URL encoded with UTF-8 character encoding (even for sending non-ASCII domain names).

 

Error Codes:

1701:Success, Message Submitted Successfully, In this case you will receive the response 1701|<CELL_NO>|<MESSAGE ID>, The message Id can then be used later to map the delivery reports to this message. 1702:Invalid URL Error, This means that one of the parameters was not provided or left blank

1703:Invalid value in username or password field

1704:Invalid value in "type" field

1705:Invalid Message

1706:Invalid Destination

1707:Invalid Source (Sender)

1708:Invalid value for "dlr" field

1709:User validation failed

1710:Internal Error

1025:Insufficient Credit

 

Note:-

  • Along with the above errors codes, standard SMPP v3.4 error codes may also be returned where applicable.
  • Apart from 1709, Please DO NOT RETRY re-sending the message for any other error code (including SMPP v3.4 Error codes ).

 

Bulk SMS API Reply Format:

<Error_Code>|<destination>|<message_id>,<Error_Code>|<destination>|<message_id>...

 

Exceptional Situations:-

A request containing multiple destinations will be aborted immediately if any error other than “Invalid Destination” is found, in case an invalid destination is found we just skip that destination and proceed to the next destination.

If while processing the request the SMPP Server goes down, the HTTP API will retry a fixed number(with a gap of ten milliseconds between consecutive retries) of times to reconnect to the SMPP server and submit the message. In case the SMPP server does not come up before the fixed number of attempts are exhausted, the batch will be aborted at that destination and a message will be returned in following format:-

<Error_Code>|<destination>|<message_id>,<Error_Code>|<destination>|<message_id>,1709|<destination_at_which_batch_aborted>

The third and final situation which can arise is the the credits can get exhausted in the middle of a request being serviced. In case such a situation occurs we will be aborting the batch on the destination at which we got the “Insufficient_Credit” error, and a response in the following format will be returned to the client:-

<Error_Code>|<destination>|<message_id>,<Error_Code>|<destination>|<message_id>,1025|<destination_at_which_batch_aborted>

 

Example Link to Submit Plain Text Messages (GSM 03.38 character set):

 

http:// <server>:<port>/bulksms/bulksms?username=XXXX&password=YYYYY&type=0&dlr=1&destination= %2B9198181818&source=xxxxxxx&message=Demo%20Message!!!

 

The following observations can be made in the above URL:-

  1. 'type=0', indicates this is a message of type plain text, this mode supports all characters falling under the GSM 03.38 character set.
  2. 'dlr=1', indicates delivery report for this message is enabled.
  3. 'message=Demo%20Message!!!', The message field contains the content to send in an URL encoded format, on using the appropriate username and password in the above link you will get the 'Demo Message!!!' on your mobile phone.
  4. 'destination=%2B919818181', An optional plus is included in the destination field here, Do note that the ‘+’ sign is URL encoded.

 

 

Example Link to Submit Plain Text Messages (ISO-8859-1 Character set):

 http:// <server>:<port>/bulksms/bulksms?username=XXXX&password=YYYYY&type=5&dlr=0&destination=91981818181&sour ce=xxxxxxxx&message=Demo%20Message!!!

 

The following observations can be made in the above URL:-

  1. 'type=5', indicates message is of type plain text, this mode supports all characters falling under the ISO-8859-1 character set.
  2. 'dlr=0', indicates delivery report for this message is not enabled.
  3. 'message=Demo%20Message!!!', the message field contains the message to send in an URL encoded format, on using the appropriate username and password in the above link you will get the message “Demo Message!!!” on your mobile phone.
  4. 'destination=91981818181' , the optional ‘+’ has been omitted.

 

Example Link to Submit Flash Messages (GSM 03.38 Character set):

http:// <server>:<port>/bulksms/bulksms?username=XXXX&password=YYYYY&type=1&dlr=0&destination=91981818181&sour ce=xxxxxxxx&message=Demo%20Message!!!

On calling the above link by replacing the username and password by your account username and password, the message ‘Demo Message!!!’ should display on your cell phone.

The characters in the message field should fall in the GSM 03.38 character set and the type parameter has to be set to 1 i. e. (type=1).

 

Example Link to Submit Unicode Flash Messages :

http:// <server>:<port>/bulksms/bulksms?username=XXXX&password=YYYYY&type=6&dlr=0&destination=919818181&source

=xxxxxxxx&message=00440065006D006F0020004D0065007300730061006700650

02100210021

 

On calling the above link by replacing the username and password by your account username and password, the sms ‘Demo Message!!!’ should flash on the mobile no in the destination field.

The message has to be encoded in the UTF-16BE format and the type parameter has to be set to 6 i.e. (type=6).

 

Example Link to Submit Unicode Messages :

http:// <server>:<port>/bulksms/bulksms?username=XXXX&password=YYYYY&type=2&dlr=0&destination=9198121212&sourc e=xxxxxxxx&message=00440065006D006F0020004D006500730073006100670065002100210021

 

On calling the above link by replacing the username and password by your account username and password, you should get the sms ‘Demo Message!!!’ on the mobile no in the destination field.

The message has to be encoded on the UTF-16BE format and the type parameter has to be set to 6 i.e. (type=2).

 

 
GSM 03.38 Character set


ISO 8859 Character Set

 

Calling HTTP API Using php

<?php class Sender
{
   var $host; var $port;

/*

*  Username that is to be used for submission

*/ var $strUserName;

/*

*  password that is to be used along with username

*/ var $strPassword;

/*

*  Sender Id to be used for submitting the message

*/ var $strSender;

/*

*  Message content that is to be transmitted

*/ var $strMessage;

/*

*  Mobile No is to be transmitted.

*/ var $strMobile;

/*

*  What type of the message that is to be sent

*  <ul>

*  <li>0:means plain text</li>

*  <li>1:means flash</li>

*  <li>2:means Unicode (Message content should be in Hex)</li>

*  <li>6:means Unicode Flash (Message content should be in Hex)</li>

*  </ul> */

var $strMessageType;

/*

*  Require DLR or not

*  <ul>

*  <li>0:means DLR is not Required</li>

*  <li>1:means DLR is Required</li>

*  </ul> */

   var $strDlr;

   private function sms__unicode($message)
  {

      $hex1='';

      if (function_exists('iconv'))
     {

        $latin = @iconv('UTF-8', 'ISO-8859-1', $message); if (strcmp($latin, $message)) { $arr = unpack('H*hex', @iconv('UTF-8', 'UCS-2BE', $message));

        $hex1 = strtoupper($arr['hex']);

     }

     if($hex1 ==''){ $hex2=''; $hex=''; for ($i=0; $i < strlen($message); $i++){

     $hex = dechex(ord($message[$i]));

     $len =strlen($hex); $add = 4 - $len; if($len < 4){ for($j=0;$j<$add;$j++){

     $hex="0".$hex;

  }

}

$hex2.=$hex;

}

return $hex2;

}

else{ return $hex1;

}

}

else{

print 'iconv Function Not Exists !';

}

}

//Constructor.. public function Sender ($host,$port,$username,$password,$sender, $message,$mobile, $msgtype,$dlr){

$this->host=$host;

$this->port=$port;

$this->strUserName = $username;

$this->strPassword = $password;

$this->strSender= $sender;

$this->strMessage=$message; //URL Encode The Message..

$this->strMobile=$mobile;

$this->strMessageType=$msgtype;

$this->strDlr=$dlr;

}

public function Submit(){ if($this->strMessageType=="2" || $this->strMessageType=="6") { //Call The Function Of String To HEX.

$this->strMessage = $this->sms__unicode(

$this->strMessage); try{

//Smpp http Url to send sms.

$live_url="http://".$this->host.":".$this->port."/bulksms/bulksms?username=".$this->strUserName."&password=".$this->strPassword."&type=".$this->strMessageType."&dlr=".$this>strDlr."&destination=".$this->strMobile."&source=".$this->strSender."&message=".$this->strMessage."";

$parse_url=file($live_url); echo $parse_url[0]; }catch(Exception $e){

echo 'Message:' .$e->getMessage();

}

}

else

$this->strMessage=urlencode($this->strMessage); try{

//Smpp http Url to send sms.

$live_url="http://".$this->host.":".$this->port."/bulksms/bulksms?username=".$this->strUserName."&password=".$this->strPassword."&type=".$this->strMessageType."&dlr=".$this->strDlr."&destination=".$this->strMobile."&source=".$this->strSender."&message=".$this->strMessage."";

$parse_url=file($live_url);

echo $parse_url[0];

}

catch(Exception $e){ echo 'Message:' .$e->getMessage();

}

}

}

//Call The Constructor.

$obj = new Sender("IP","Port","","","Tester"," "ةي       برع لا"," 919990001245,"2","1");

$obj->Submit ();

?>

  • API, Bulk SMS API, SMS API Specification
  • 0 Корисниците го најдоа ова како корисно
Дали Ви помогна овој одговор?

Понудени резултати

SMS2App (SMS-Application Integration)

The documentation here covers basic guide on how you can capture your clients' SMS from our...

Bulk, Group SMS-in-your-Application/Program

Have you ever thought of how your Bank sends an SMS alert to you instantly after withdrawing...

DND Policy as instructed by NCC

Please be advised that effective 1st July, 2016, all GSM Networks in Nigeria...

Powered by WHMCompleteSolution