SMSWAY Gateway API;

Documentation for the SMSWay API v1.5

API for SMSWay Gateway

Documentation for the SMSWay API v1.5 2011 © www.smsway.eu

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 6. Free support .................................................................................................................................................... 9

Documentation for the SMSWay API v1.5 2011 © www.smsway.eu

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)

Optional parameters

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.

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

The result of each sent is available in your SMSWay account. Documentation for the SMSWay API v1.5 2011 © www.smsway.eu

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

20

Data missing

Documentation for the SMSWay API v1.5 2011 © www.smsway.eu

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

Documentation for the SMSWay API v1.5 2011 © www.smsway.eu

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 • ERR_05 – server side error

Documentation for the SMSWay API v1.5 2011 © www.smsway.eu

6. Examples 6.1 Sending single message in PHP (with curl extension)

Documentation for the SMSWay API v1.5 2011 © www.smsway.eu

6.2 Sending single message in PHP (without curl extension)

6.3 Callback report collecting in PHP