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

(1)

Documentation for the SMSWay API v1.5

(2)

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 : http://www.smsway.eu

2. Single SMS Message sending

Méthode HTTP : GET / POST

http://api.smsway.eu/manage.php

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

single SMS. Optional parameters

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-8859-1, ASCII, EUC-JP, SJIS (case sensitive).

Return codes

sended Message successfully acknowledged

ERR_01 Invalid apikey

ERR_02 Invalid recipient

ERR_03 Not enough money on SMSWay account

ERR_04 Empty SMS content

ERR_05 Service unavailable (server side error)

ERR_06 Unknown error

(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 : http://www.MyPage.com/status_update.php

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

(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 : http://www.MyPage.com/incoming_record.php

The URL must begin with either http:// (non-encrypted) or https:// (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:

http://api.smsway.eu/manage.php?action=balance&apiKey=*************

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

(7)

6. Examples

6.1 Sending single message in PHP (with curl extension)

<?

// config

$apiKey = "*************"; // your personal api-key

$num = "32488112233"; // 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-8859-1,

ASCII, EUC-JP, SJIS // exec

$url = "http://api.smsway.eu/manage.php?apiKey=".urlencode($apiKey)."&content=".u

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 = "32488112233"; // 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-8859-1,

ASCII, EUC-JP, SJIS // exec

$url = "http://api.smsway.eu/manage.php?apiKey=".urlencode($apiKey)."&content=".u

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 : www.smsway.eu

E-mail : support@smsway.eu Hotline : +32-2-888-60-30