Documentation for the SMSWay API v1.5
Table of contents
1. Introduction ... 3
1.1 How to start ... 3
2. Single SMS Message sending ... 3
3. Callback procedure – delivery confirmation status ... 4
4. Checking the account balance ... 6
5. Examples ... 7
5.1 Sending single message in PHP (with curl extension) ... 7
5.2 Sending single message in PHP (without curl extension) ... 8
5.3 Callback report collecting in PHP ... 8
5.4 Sending single message in other languages ... 8
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
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
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
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
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; ?>
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 !
7. Free support
If you have any further questions, contact the free support of SMSWay. Website : www.smsway.eu
E-mail : [email protected] Hotline : +32-2-888-60-30