Documentation for the SMSWay API v1.5. API for SMSWay Gateway. Documentation for the SMSWay API v

Transcription

1 API for SMSWay Gateway

2 Table of contents 1. Introduction How to start Single SMS Message sending Callback procedure delivery confirmation status Checking the account balance Examples Sending single message in PHP (with curl extension) Sending single message in PHP (without curl extension) Callback report collecting in PHP Sending single message in other languages Free support... 9

3 1. Introduction SMSWay is a high quality SMS platform which enables you to integrate any of your applications with our SMS message sending system. The main advantage of our system is its simplicity of implementation. The SMS message can have your company name or any phone number that you owns. Every message sent in our system has its own unique id which allows you to receive its delivery confirmation. 1.1 How to start To start using SMSWay API you need to register and create an account on our website. Registration is completely free. Your account is ready to use just after you register. URL : 2. Single SMS Message sending Méthode HTTP : GET / POST Parameters apikey (apikey) Your personal api-key (available in your SMSWay account). Strictly confidential. num (string) Phone number of the recipient (in international format, without + or 00) content (string) Content of your SMS message. The maximal message length is set to 457. In case of a long SMS message (more than 160 chars), our system will automatically divide it into several single messages and charge them. messages. The divided messages then will be sent and delivered to the recipient s phone as a Optional parameters single SMS. from (string) SenderID (11 alphanumerical characters maximum) hlr (yes-no) HLR Lookup before sending (check recipient number). + EUR 0.01 incl. VAT msgid (string) Optional custom value sent with SMS (ex:123). Max 50 chars. encoding (string) You can set different encoding of messages. Available encodings types are: UTF-8, UTF7-IMAP, ISO , ASCII, EUC-JP, SJIS (case sensitive). Return codes sended ERR_01 ERR_02 ERR_03 ERR_04 ERR_05 ERR_06 Message successfully acknowledged Invalid apikey Invalid recipient Not enough money on SMSWay account Empty SMS content Service unavailable (server side error) Unknown error The result of each sent is available in your SMSWay account.

4 3. Callback procedure delivery confirmation status We offer you a possibility to run any available script in the web with callback delivery report. In order to use this option please log in on your SMSWay account and set the «Callback URL» under «My Account» tab. Example : We suggest you to check the correctness of your script address before its submission. When this request is called, the system will respond and pass to your script all parameters needed for delivery confirmation (GET method is used). Return GET variables msgid (int) Optional custom value sent with SMS (ex:123) provided while calling the API status (int) Status code num (string) Phone number of the recipient (in international format, without + or 00) timesent (timestamp) Time (unix) on of the message when its sent timereceived (timestamp) Time (unix) of delivery report cost (int) Price per SMS (in EURO, incl. VAT) *All characters are case sensitive. Status codes (status GET variable) 100 Delivered 1 Rejected: Message length is invalid 2 Subscriber absent 3 Device memory capacity exceeded 4 Equipment protocol error 5 Equipment not supported 6 Equipment not SM equipped 7 Unknown service centre 8 Service centre congestion 9 Undeliverable 10 Rejected: Invalid source address 11 Invalid destination address 12 Illegal subscriber 13 Teleservice not provisioned 14 Illegal equipment 15 Call barred 16 Facility not supported 17 Subscriber busy for SM 18 System failure 19 Message waiting, list full 20 Data missing

5 21 Unexpected data value 22 Resource limitation 23 Initiating release 24 Unknown alphabet 25 USSD busy 26 Duplicated invoke ID 27 No supported service 28 Mistyped parameter 29 Unexpected response from peer 30 Service completion failure 31 No response from peer 32 Invalid response received 34 Invalid destination 49 Message type not supported 50 Destination blocked for sending 51 Not enough money 52 No price 67 Invalid esm_class field data 69 Rejected by SMSC 72 Rejected: Invalid source address TON 73 Rejected: Invalid source address NPI 80 Rejected: Invalid destination address TON 81 Rejected: Invalid destination address NPI 88 Throttling error 401 Invalid ID 402 Message expired 403 Message acknowledged 409 Queued 900 Unknown error

6 4. Incoming SMS Message Callback We offer you a possibility to run any available script in the web with incoming messages. In order to use this option please log in on your SMSWay account and set the «Callback URL for Incoming Messages» under «My Account» tab. Example : The URL must begin with either (non-encrypted) or (encrypted). The SMSWay server sends HTTP GET queries to your URL with the variables listed below. Return GET variables msgid (int) A unique ID assigned to an incoming message. sender (int) The sender s phone number / senderid dest (string) Phone number of the recipient message (string) The message s text, in the UTF-8 character set. timestamp (timestamp) The time of receiving the message, in Unix time format. *All characters are case sensitive. 5. Checking the account balance Our customers can check their current account balance by using the balance script. In order to use the script, the users have to provide their apikey at the following URL: If the user credentials have been authenticated, the script will return the balance. If some of the details are incorrect, the script will return the error message accordingly. The following are the error messages which can be returned by the script: ERR_01 empty or invalid apikey ERR_05 server side error

7 6. Examples 6.1 Sending single message in PHP (with curl extension) <? // config $apikey = "*************"; // your personal api-key $num = " "; // destination number in international format $content = "Hello World!"; // SMS content, 457 characters max $from = ""; // senderid of SMS, max 11 alphanumeric characters $hlr = "no"; // (yes-no) number verification before sending (EUR 0.01 incl. VAT) $msgid = ""; // Optional custom value sent with SMS (ex:123) $encoding = ""; // Encoding of message content. UTF-8, UTF7-IMAP, ISO , ASCII, EUC-JP, SJIS // exec $url = " rlencode($content)."&num=".$num."&from=".$from."&hlr=".$hlr."&msgid=".$msgid."&en coding=".$encoding; $session = curl_init($url); curl_setopt($session, CURLOPT_URL,$url); curl_setopt($session, CURLOPT_RETURNTRANSFER,true); curl_setopt($session, CURLOPT_POST, false); curl_setopt($session, CURLOPT_HEADER, false); curl_setopt($session, CURLOPT_TIMEOUT,120); curl_setopt ($session, CURLOPT_FRESH_CONNECT, true); curl_setopt ($session, CURLOPT_SSL_VERIFYPEER,false); curl_setopt ($session, CURLOPT_SSL_VERIFYHOST,false); $response = curl_exec($session); curl_close($session); // result if ($response=="sended") echo "SMS ok"; else echo $response;?>

8 6.2 Sending single message in PHP (without curl extension) <? // config $apikey = "*****************"; // your personal api-key $num = " "; // destination number in international format $content = "Hello World!"; // SMS content, 457 characters max $from = ""; // senderid of SMS, max 11 alphanumeric characters $hlr = "no"; // (yes-no) number verification before sending (EUR 0.01 incl. VAT) $msgid = ""; // Optional custom value sent with SMS (ex:123) $encoding = ""; // Encoding of message content. UTF-8, UTF7-IMAP, ISO , ASCII, EUC-JP, SJIS // exec $url = " rlencode($content)."&num=".$num."&from=".$from."&hlr=".$hlr."&msgid=".$msgid."&en coding=".$encoding; $response = file($url); // response if ($response[0]=="sended") echo "SMS ok"; else echo $response[0];?> 6.3 Callback report collecting in PHP <?php // If SMS was sent with msgid parameter, callback will return it in variable $_GE T["msgid"] $msgid=$_get["msgid"]; $status=$_get["status"]; $number=$_get["number"]; $timereceived=$_get["timereceived"]; $timesent=$_get["timesent"]; $cost=$_get["cost"]; if($_get["msgid"] && $_GET["status"] ) { ' mysql_query("update sms SET sms_status = '".$status."', sms_cost = '".$cost." WHERE sms_id = '".$msgid."' LIMIT 1"); echo "OK"; }?> 6.4 Sending single message in other languages This application is also available with other languages (PERL, ASP, etc.) : the URL and parameters stay the same, it s up to you to code with your favorite language!

9 7. Free support If you have any further questions, contact the free support of SMSWay. Website : [email protected] Hotline :