smsapi http en

Documentation for SMSAPI (https)Version 2.28.0

Documentation SMSAPI (https) Wersja 2.28.0

Table of contents

1. Introduction

1.1 How to start

1.2 IP filter for API interface

1.3 API password

I. SMS SENDING

2. Single SMS Message sending

2.1 ECO messages sending

2.2 Fast messages sending

2.3 Scheduled SMS sending

2.4. Deleting scheduled messages

3. Multiple SMS sending

3.1 Sending messages to phonebook's group

3.2 Multiple personalized SMS sending using personalization parameters

3.3 Multiple SMS sending using IDX parameter

3.4 Sending message with discount codes

4. Sending messages using templates

5. WAP PUSH messages

6. Sending vCard messages

7. mail2SMS – Sending SMS using e-mail

8. Account balance checking

II. SENDING MMS MESSAGES

9. Sending MMS messages

III. SENDING VMS MESSAGES

10. Sending VMS messages

IV. MESSAGES DELIVERY CONFIRMATION RECEIVING

11. SMS delivery confirmation receiving – CALLBACK procedure

12. MMS delivery confirmation receiving – CALLBACK procedure

13. VMS delivery confirmation receiving – CALLBACK procedure

14. Bulk CALLBACK

ComVision 2013Page no: 2/30 go to the table of contents


V. SMS AND MMS MESSAGES RECEIVING

15. SMS/MMS receiving

15.1 SMS receiving

15.2 MMS receiving

VI. HLR LOOKUP SERVICE

16. HLR Lookup

VII. SUMMARATION

17. Last sentence

Appendix 1 – Delivery reports list

Appendix 2 – Error codes

Appendix 3 - Encoding

Appendix 4 – Example scripts

History of changes



1. Introduction

SMSAPI is a high quality SMS platform which enables you to integrate any of your applicationswith our SMS/MMS message sending and receiving system. The main advantage of our system is itssimplicity of implementation. The SMS message can have your company name or any phone numberthat you owns. Every message sent in our system has its own unique id which allows you to receive itsdelivery confirmation.

1.1 How to start

To start using SMSAPI you need to register and create an account on our website:URL address: http://www.smsapi.pl/Registration is completely free. Your account is ready to use just after you register, but we recommendyou to verify at least one sender name or number. Every message sent before validation has the „SMSAPI“ as a default name.

1.2 IP filter for API interface

In order to improve interface API protection you may set list of IP addresses which will be whitelisted. You may do it in „USTAWIENIA” → „API” tab „Filtr adresów IP” in field Filtr adresów IP. It will be possible to send messages only from these whitelisted IP addresses (try of sending from other IPs will result in responding: ERROR:105). IP addresses should be separated by semicolon.

1.3 API password

API password after registering is the same as web panel password. You may change your API password in Ustawienia → API. Changing your web panel password doesn't change API password.

2. Single SMS Message sending

URL links needed for connecting with our application:- https://ssl.smsapi.pl/sms.do – for SSL secured connections 256bit v3.0- https://ssl2.smsapi.pl/sms.do - backup for SSL secured connections 256bit v3.0- http://api.smsapi.pl/sms.do – for unsecured connections (Unrecommended!)- http://api2.smsapi.pl/sms.do - backup for unsecured connections (Unrecommended!)

Messages should be sent as a HTTP GET or POST request to our system:

Parameter Description

username * Username used to identify a user in our system or e-mail address connected with the account

password * Password to Your account hashed with MD5

to * Mobile phone number of the recipient (i.e. 48505602702 ).

group * Name of the group from the phonebook to which message should be sent.

message * The message text. Content of one message is normally 160 characters per single SMS or 70 in case of using at least one special character (polish characters are considered to be special characters). The maximal message is set to 918 normal characters or 402 if special chars are used and it is being sent as one block of 6 messages joined together and charged as three messages. Detailed information about special characters are given in chapter 14.

from Name of the sender. As a default the sender name is set to „SMSAPI”. Only verified names are being accepted (&from=active_name). Sender name may be set after loging into web panel on www.smsapi.pl in USTAWIENIA → POLA NADAWCY.

encoding This parameter describes the encoding of the message text. Windows-1250 is set asdefault. If another encoding is needed parameter encoding should have following vaule:

- for iso-8859-2 (latin2) – should be &encoding=iso-8859-2- for utf-8 – should be &encoding=utf-8



flash Sending a massage in flash mode can be activated by setting this parameter to „1”. Flash SMS are automatically presented on the mobile screen and have to be saved to be stored in inbox. (&flash=1)

test When parameter test is set to „1” message won't be sent but response will be displayed, there is no charge for such test messages. (&test=1)

details When details parameter is set to „1” more details in response will be displayed (message, lenght and sms count). (&details=1)

date Date in unix timestamp (&date=1287734110) or in ISO 8601 (&date=2012-05-10T08:40:27+00:00) when message will be sent (&date=1287734110). Setting a past date will result in sending message instantly.

date_validate Check if date if given in proper format. Returns ERROR:54 if not

datacoding This parameter allows to send WAP PUSH messages. (&datacoding=bin)

skip_foreign Setting this parameter (&skip_foreign=1) causes skipping all non-polish numbers from the request and sending message only to Polish ones.

idx Optional custom value sent with SMS and sent back in CALLBACK. Parameetr idx may contain up to 36 chars, allowd are digits 0 – 9 and letters a – z (parameter is not case sensitive). (&idx=123)

check_idx If this parameter is set (&check_idx=1) system checks if message with the same idx value was already sent, if yes error 53 is returned.

sms2way Setting this parameter to „1” (&sms2way=1) will result in sending 2way message.

eco Setting this parameter to „1” will result in sending ECO message (ECO messages are sent with 9-digits phone number in sender name)

nounicode Setting this parameter prevents from sending messages containing special charackters. ERROR: 11 will be returned when the message contains special charackters.

normalize Setting this parameter to “1” result in changing inter alia polish chars like “ą”, “ś”, “ć” etc. to “a”, “s”, “c”. The full list of chars that may be changed is in section 15. Last sentence. Attention! Appearing other special chars than presented in Last sentencewill result in sending message in encoding like “with special chars”

fast Setting this parameter to „1” will result in sending message with the highest priority which ensures the quickest possible time of delivery. This parameter may be used for both PRO and ECO messages. Fast messages costs 50% more than normal message. Attention! Mass and marketing messages musn't be sent with fast parameter.

partner_id Partner code which you will get after signing Partner agreement.

max_parts Defines maximum message parts allowed, maximum value allowed is 6. ERROR: 12 will be returned when the message has more parts than defined.

expiration_date Message expiration date (in unix timestamp) is a date after which message won't be delivered if it wasn't delivered yet. The difference between date sent and expiration date can't be less than 1 hour and more than 12 hours. Time will be set with tolerance +/- 5 minutes.

discoint_group Name of the discounts' codes group from which codes should be sent. Groups can be added or edited in customers panel.

notify_url This parameter allows to set URL address to delivery report receiving callback scriptfor this specific messages. This URL will be used instead of global callback script URL set on the account. ATTENTION! This Parameter may be used only for single messages.

• - required field

Attention! Parameters group and to are exchangeable, one of these two parameter has to appear in a request. Lack of any or appearing both of them will result in returning ERROR:13.s



Request: https://ssl.smsapi.pl/sms.do?username=username&password=md5(password)&from=sender_name&to=48500500500&message=message_content

Response: OK:<ID>:<POINTS>

or (when error occur)

ERROR:<ERR>

<ID> Message unique ID. You will need it for delivery corfirmation<POINTS> Amount of used credits (i.e. Text sent in 3 messages will return 3xSMS

amount)<ERR> Error code (check the error code list in Appendix 2)

Example: OK:17101000090360359:0.165orERROR:102

In case of any problems with sending requests to basic URL (as in example above) backup URL may be used: https://ssl2.smsapi.pl/

2.1 ECO messages sending

ECO messages are being sent from random 9-digits polish phone number (no possibili of setting alphanumeric sendername). To send ECO messages parameter &eco should be set to „1” (&eco=1) also for mass sendings.

Request: https://ssl.smsapi.pl/sms.do?username= username & password=md5(password)&to=48500500500&eco=1&message=ECO_message_content



ERROR:<ERR>




In case of any problems with sending requests to basic URL (as in example above) backup URL may be used: https://ssl2.smsapi.pl/.


http://api.smsapi.pl/sms.do?username=username&password=md5(password)&to=48500500500&eco=1&message=ECO_message_content







2.2 Fast messages sending

Setting parameter fast to „1” (&fast=1) ill result in sending message with the highest priority which ensures the quickest possible time of delivery. This parameter may be used for both PRO and ECO messages. Fast messages costs 50% more than normal message.

Request: https://ssl.smsapi.pl/sms.do?username= username &password= password &to=48500500500&fast=1&message= Fast_message _content



ERROR:<ERR>





ATTENTION! Mass and marketing messages musn't be sent with fast parameter. In case of sendingmessage to more than one recipient in a single request messages will be sent as normal ones, withoutparameter &fast=1.

2.3 Scheduled SMS sending

To send message at specified date and hour parameter &date has to be used. This parameter should be in unix timespamp format.2.5 Sending messages to phoneb

Zapytanie: https://ssl.smsapi.pl/sms.do?username= username&password= md5(password)&to48500500500&date=1577878200&message=scheduled_message_content



ERROR:<ERR>



http://api.smsapi.pl/sms.do?username=username&password=password




http://api.smsapi.pl/sms.do?username=username&password=password&to=48500500500&fast=1&message=Fast_message











2.4. Deleting scheduled messages



password * Password to Your account hashed in MD5

sch_del* ID of message to delete (returned after sending one). * - required fields

Request: https://ssl.smsapi.pl/sms.do?username=username&password=md5(password)&sch_del=09040616088106874

Response: OK

or (when ID od message doesn't exist)

ERROR:301

Example ID: 09040616088106874




3. Multiple SMS sending

Sendiing messages to a group of recipients is similar to single submission (presented inchapter 2). The only difference is filling field to with multiple set of recipients numbers. In order tosuccessfully send this type of message, we recommend to pass all parameters in a HTTP POSTrequest just to assure that all recipients numbers will be submitted correctly. Using

If the total cost of sending this message is greaterhan the number of available credits onuser's account, the system will respond 103 error code and all messages will be rejected.

If some of given recipient's numbers will be invalid (unrecognized by SMSAPI due to wrongprefix or landline number) than these numbers will be skipped and all other will be sent. Deliveryreports will not cocern the skipped numbers. If any number will appear more than once in one requestmessage will be sent only once to this recipient.

Request: https://ssl.smsapi.pl/sms.do?username=username&password=md5(password)&from=sender_name&to=48500500500,48501501501,48502502502&message=message

Response: OK:<ID>:<POINTS>:<PHONE>;...;...;...

<ID> Message unique ID. You will need it for delivery corfirmation<POINTS> Number of used credits (i.e. Text sent in 3 messages will return 3xSMS

amount)<PHONE> Recipient's phone number

Example:OK:17101000090567759:0.14:500500500;OK:171010000903455357:0.14:501500501;OK:17101000096577326:0.14:502502502;

Notice that in multiple SMS sending recipients' numbers are in response as well, and all message data are separate by a semicolon (after the last message there is semicolon as well).

Recommended maximum number of messages sent in one request for POST method is 10000, for GET method it is 200 messages.


3.1 Sending messages to phonebook's group

To send messages to specified group first this group should be created in web panel on www.smsapi.pl in menu KSIĄŻKA TELEFONICZNA (ang.: phonebook). An example is presented below:

Request: https://ssl.smsapi.pl/sms.do?username=username&password=md5(password)&group=test_group&message=Message_content




Example:OK:17101000090567759:0.14:500500500;OK:171010000903455357:0.14:501500501;OK:17101000096577326:0.14:502502502;




3.2 Multiple personalized SMS sending using personalization parameters

There is possibility to send up to 100 personalized messages in one request using personalizationparameters. To send more personalized messages more than one request have to be used.Personalization parameters should be definied in request as param1, param2, param3, param4,which will replace [%1%], [%2%], [%3%] oraz [%4%] in message content. Values of theseparameters have to be separate by pipe char „|” according to the template below:

param1=Ania|Michal|Andrzej&param2=Nowak|Kowalski|Nowakowski

The number of parameters has to be exactly the same as number of recipients in a request otherwise ERROR: 18 will be returned and message won't be sent.

IMPORTANT! Length of message ma be different depending on the length of parameter value.If one of numbers will be invalid message to this number will be skipped and the rest will be sent.

ParametersAfter definying parameters the may be used in message content:

[%1%] Value of parameter 1 (param1)




Example:

https://ssl.smsapi.pl/sms.do?username=username&password=password&from=sender_name&to=48600111222,48500111222&mess age=Message content, parametr1: [%1%] parametr2: [%2%] &param1=Jan|Ania&param2=30|40

Message will have following contents:Message 1 : Message content, parametr1: Jan parametr2: 30Message 2 : Message content, parametr1: Ania parametr2: 40


3.3 Multiple SMS sending using IDX parameter

There is possibility to send mass messages with custom parameter IDX different for each mesage.This parameter then is returned in CALLBACK. With parameter idx additional parameter check_idx(&check_idx=1). Using check_idx parameter prevents from two message with the same idx parametervalue. To use it add at the end of request:

&idx=idx1|idx2|idx3|idx4

Number of IDX parameters have to be equal to the number of recipients' number given in request.




3.4 Sending message with discount codes

SMSAPI allwos to send messages with discount codes in the message content. To sendmessages with discount codes you have to first prepare list of codes in web panel in menu „MOREFUNCTION” → „DISCOUNT CODES”. Code can be imported from previously prepared csv file oryou may use built in codes generator.While sending messages codes are taken from selected group are marked as used (one code can beused only one). To be able to use codes the list has to be active („Date expire” hasn't expired) andcontain enough unused codes.

Request: https://ssl.smsapi.pl/sms.do?username=username&password=password&from=sender_name&to=48500500500,48501501501,48502502502&discount_goup=codes&message=test_message_with_discount_codes:_[%kod%]_the_end.




Example:OK:17101000090567759:0.14:500500500;OK:171010000903455357:0.14:501500501;

OK:17101000096577326:0.14:502502502;

In case of any problems with sending requests to basic URL (as in example above) backup URL may be used https://ssl2.smsapi.pl/.



4. Sending messages using templates

Using templates it is very easy to change standard notification messages (ma be used inshops, internet services, medical clinics etc.) without changing php script that implements SMSsending.

To use templates You should:• After loging on http://www.smsapi.pl add tempate in „SMS” „Ustawienia” „Szablony”→ →

• Places which should be replaced by a parameter shoul be given [%N%] where N is numberbetween 1 and 4 (parameter number)

• To use a template in API request there should appear &templates=template_name in the request• Apart from all basic parameters while using templates following parameters are available:

Parameter Descripction

template Template name

paramNThe value of this parameter will replace [%N%] in the template wherew N is a number between 1 and 4

singleIf the message will contain more than 160 chars (single message) it won't be sent and ERROR:12 will be replied (&single=1)

Example:Template name: NotifyTemplate content: Hello [%1%], Your order has been sent. The shipment number is [%2%] You ma y follow it on our site.

https://ssl.smsapi.pl/sms.do?username=username&password=password&from=sender_name&to=48600111222&template=Notify&param1=Marcin&param2=BG12344423

The content of sent message: Hello Marcin, Your order has been sent. The shipment number i BG12344423 You ma y follow it on our site.


5. WAP PUSH messages

To send WAP PUSH message the link and message content have to be be coverted to binnary. Itmay be done using a coverter that may be found in tab POMOC on https://www.smsapi.pl.

The result of the conversion should be given in a request as a message content. There should be used following parameters &datacoding=bin and &udh=0605040b8423f0 in API request.

Example:https://ssl.smsapi.pl/sms.do?username=username&password=password&from=sender_name&to=48501502503&datacoding=bin&udh=0605040b8423f0&message=0605040b8423f0860601ae02056a0045c60c03687474703a2f2f7777772e736d736170692e706c000701034e61737a61207374726f6e613a000101



https://www.smsapi.pl/

http://api.smsapi.pl/send.do?username=login&password=haslo_md5&from=nadawca&to=48600111222&template=powiadom&param1=Jan,Ania&param2=30,40

http://www.smsapi.pl/


6. Sending vCard messages

To send vCard message the link and message content have to be be coverted to binnary. It maybe done using a coverter that may be found in tab POMOC on https://www.smsapi.pl

The result of the conversion should be given in a request as a message content. There should be used following parameters &datacoding=bin and &udh=06050423F40000 in API request.

Example:https://ssl.smsapi.pl/sms.do?username=username&password=password&from=sender_name&to=48501502503&datacoding=bin&udh=06050423F40000&message=

In case of any problems with sending requests to basic URL (as in example above) backup URL may be used: https://ssl2.smsapi.pl/

7. mail2SMS – Sending SMS using e-mail

To send sms using mail2sms e-mail should be created according to followin scheme: TO: [email protected]: username@password_hashed_in_md5CONTENT: from=sender_name&to=number&message=message_content

ATTENTION! Password should be given hashed in MD5

Example: TO: [email protected]

SUBJECT: username@8456fkty567gb3bg37b357b3457b3457 CONTENT: from=sender_name&to=number&message=message_content

Adding parameter raport=1 will result in sending back e-mail with report (sent confirmation or error code – this is useful while testing the service):

TO: [email protected] SUBJECT: username@ password_hashed_in_md5

CONTENT: from=sender_name&to=number&raport=1&message=message_content

Mail may be sent in plain / quotedprintable / base64 encoding.

All parameters presented in Section 2. “Single SMS message sending” are available in mail2sms.

Sender name (parameter &from=) has to be active. To send ECO message using mail2SMS parameter &eco=1 has to be used.

IMPORTANT! Thne recipient's number musn't start with „+” sign. Parameter „message” must be at the end of e-mail.



8. Account balance checking

User's account administration is done by sending HTTP GET or POST request to our system:


username * Username used to identify a user in our system

password * API password to Your account hashed with MD5

credits* &credits=1• - required field

Request: https://ssl.smsapi.pl/sms.do?username=username&password=password_in_md5 &credits=1

Response: Points: <POINTS>


ERROR:<ERR>

<POINTS> number of points available for this user

Example: Points: 100

9. Sending MMS messages

For sending MMS messages please send a request to one of following address https://ssl.smsapi.pl/mms.do (Not recommended!) or https://ssl.smsapi.pl/mms.do for SSL connections with proper parameters.

The following table describes parameters that are required to send MMS message:






subject * MMS message subject. Subject may contain up to 30 characters, if subject is longer error 26 is returned.


smil * MMS message in SMIL (example in Appendix 4)

idx Optional custom value sent with SMS and sent back in CALLBACK. Parameetridx may contain up to 36 chars, allowd are digits 0 – 9 and letters a – z (parameter is not case sensitive). (&idx=123)


• - required fields

Attention! Parameters group and to are exchangeable, one of them has to be in the request. Lack of any of them will return ERROR: 13 in the result.


http://api.smsapi.pl/send.do?username=uzytkownik&password=haslo&to=48500500500

http://api.smsapi.pl/send.do?username=uzytkownik&password=haslo&to=48500500500


Request: https://ssl.smsapi.pl/mms.do?username=username&password=password&to=48500500500&subject=TestMMS&smil=[smil]



ERROR:<ERR>

<ID> MMS message unique ID. You will need it for delivery corfirmation<POINTS> Amount of used credits (i.e. Text sent in 3 messages will return 3xSMS



E XAMPLE OF SENDING MMS


10. Sending VMS messages

For sending MMS messages please send a request to one of following address https://ssl.smsapi.pl/vms.do (Not recommended!) or https://ssl.smsapi.pl/vms.do for SSL connectionswith proper parameters.

The following table describes parameters that are required to send MMS message.




from * Calling number. Leaving this parameter empty causes sending message with default calling number. Only verified and accepted number may be used. Number may be added in SMSAPI's web panel in menu VMS → CALLING NUMBERS



tts * The content of message in written text in UTF-8 encoding (for other encoding Error:11 will be returend).

File * Content of message in wave file, acceptable are URL to file existing in web ora a file sent by multipart from-data method


try Number of delivery tries when call is not answered or rejected

interval An interval between tries (min 1800s)

skip_gsm Setting this parameter (skip_gsm=1) results in skipping GSM numbers and



send VMS only to landline ones

idx Optional custom value sent with SMS and sent back in CALLBACK. Parameetr idx may contain up to 36 chars, allowd are digits 0 – 9 and letters a – z (parameter is not case sensitive). (&idx=123)


tts_lector Defines name of lector which will read typed text. Available lectors: agnieszka, ewa, jacek, jan, maja. Default value: jan. Error 35 shows when wrong value given.

• - required fields

Attention! Parameters tts and file are exchangeable, in a request should appear on of them. Lack of them or appearing both will result in not sending the message and responding ERROR: 11. Attention! Parameters group and to are exchangeable, in a request should appear on of them. Lack of them or appearing both will result in not sending the message and responding ERROR: 13.

Request: https://ssl.smsapi.pl/vms.do?username=username&password=password&to=48500500500&tts=test_message

or: https://ssl.smsapi.pl/sms.do?username=username&password=password&&to=48500500500&file=http://address.to/file.wav



ERROR:<ERR>

<ID> VMS message unique ID. You will need it for delivery corfirmation<POINTS> Amount of used credits (i.e. Text sent in 3 messages will return 3xSMS



ATTENTION! Voice messages may be sent only between 8am and 9 pm. Requests submitted betwwen 9pm and 8am will be sent at 8am.

11. SMS delivery confirmation receiving – CALLBACK procedure

We offer You possibility to run any available sctipt in the web with callback delivery reports. Inorder to use this option please login on our site https://www.smsapi.pl and set the „Adres callback -raporty SMS” in „Ustawienia” → „API” tab „Adresy callback”.

Example.: http://www.my_site.pl/status_update.phpIt is important that entered address is a valid address to existing, available script.After updating message status in SMSAPI system the update will be sent to callback script (1 to 5statuses in one request). Parameter will be sent using GET method separated by commas:

$_GET['MsgId']=09062414383994024,09062414383994025



$_GET['status']=403,404

Parameter are described in following table:


MsgId* Message ID

status* Status code, list of codes can be find in 'Appendix 1'

idx* Opcjonalny parametr użytkownika wysłany z SMS'em

donedate* Czas dostarczenia wiadomości w formacie timestamp

username* Nazwa użytkownika wysyłającego wiadomość* All characters are case sensitive

Script have to return OK (echo „OK”), otherwise the system will be sending requests every 300 seconds.

12. MMS delivery confirmation receiving – CALLBACK procedure

In order to check MMS message delivery status please log in to web panel and enter in„Ustawienia” → „API” the address to a script to which delivery statuses shoul be sent.

i.e.: http://www.my_page.pl/status_update.phpWe suggest You to check the correctness of Your scipt 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) i.e.:

MsgId=09062414383994024status=404

Following table describes parameters that are sent:


MsgId* Message ID

status* Response confirmation code (NID) – check status list in Appendix 1


donedate* Time (in timestamp) of delivery report

username* Username from wchich message was sent * All characters are case sensitive

Script has to return OK (echo „OK”), otherwise the system will be sending requests every 300 seconds.



13. VMS delivery confirmation receiving – CALLBACK procedure

In order to check VMS message delivery status please log in to web panel and enter in„Ustawienia” → „API” the address to a script to which delivery statuses shoul be sent.i.e.: http://www.my_page.pl/status_update.phpWe suggest You to check the correctness of Your scipt 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) i.e.:MsgId=09062414383994024status=404

Following table describes parameters that are sent:


MsgId* Message ID

status* Response confirmation code (NID) – check status list in Appendix 1


donedate* Time (in timestamp) of delivery report

username* Username from wchich message was sent

pressed* Key pressed while listening the message

hangup_time* Time after which recipient hang up * All characters are case sensitive


14. Bulk CALLBACK

Bulk CALLBACK script receives request the moment that sending bulk started. This feature is generally usefull for scheduled bulks. Request contains parameters presented in table below. In order to enable Bulk CALLBACK please enter CALLBACK script URL in „Settings” → „API”

Example: http://www.moja_strona.pl/bulk_callback.php

It is important that entered address is a valid address to existing, available script.

Parameter are described in following table:


type* Messages' type SMS/MMS/VMS

all* Amoint of messages (numbers) in bulk.

points* Bulk's cost

to* Points out which tab in SMS gateway was used csv, csv_and_text orphonebook.

info* When bulk i sent to groups from phonebook contains groups' names.

text* Content of sent message.* - należy zachować wielkość znaków!




15. SMS/MMS receiving

SMSAPI provides also SMS or MMS receiving service. Reponses fo ECO messages may be received (only if the response was sent up to 24h after sending ECO message). SMS and/or MMS messages may be also received on dedicated 9-digit number which is connected only with one specific client.

15.1 SMS receiving

Receiving messages may be done using CALLBACK script located on client's server. Address to this script should be entered in „Ustawienia” → „API”. The scrips works as follows:

After receiving message we will send querry to the script with POST table that contains following parameters:


sms_to Recipient's phone number

sms_from Sender phone number

sms_text Message contentent

sms_date Date in timestamp taken from the message

MsgId For ECO receiving ID of message to which this message is response, for receiving on dedicated number this field will be empty

username Username of the client to which message has been assigned

smsc SMS Centre that delivered this message

Data will be sent in UTF-8 encoding.


15.2 MMS receiving

Receiving messages may be done using CALLBACK script located on client's server. Address to this script should be entered in „Ustawienia” → „API”. The scrips works as follows:

After receiving message we will send querry to the script with POST table that contains following parameters:

POST table:


mms_to Recipient's phone number

mms_from Sender phone number

mms_subject Message subject

mms_date Date in timestamp taken from the message



FILES table:

Parametr Opis

name Original file name

type MIME type (JPEG, GIF, ...)

tmp_name Temporary file name, which has been sent to the server

error Error code (0 means no error, proper sending)

size Size of sent file (in bytes)

Data will be sent in UTF-8 encoding.

Script has to return OK (echo „OK”), otherwise the system will be sending requests every 300 seconds. E XAMPLERequests may be sent with SSL connection (https://..).

16. HLR Lookup

HLR (Home location Register) is an extent base including different kinds of information aboutevery working telephone number in GSM. In order to use this option you should request URL :https://ssl.smsapi.pl/api/hlr.do with proper parameters described below. All information about numberswill be sent to address given on our site https://ssl.smsapi.pl at „Callback address HLR” in „Settings”→ „API” tab „API Callback settings”.

It is important that entered address is a valid address to existing, available script.After checking number in HLR information about number will be send to given URL in POST table.There might be up to 20 numbers in one request.

Request: https://ssl.smsapi.pl/api/hlr.do?username=username&password=md5(password)&number=44123123123,44234234234&idx=123|234

Response: OK:<NUMBER>:<ID>:<POINTS>;OK:<NUMBER>:<ID>:<POINTS>;...;...

or

ERROR:<NUMBER>:<ERR>;ERROR:<NUMBER>:<ERR>;...;...

<NUMBER> Checked number<ID> Checking unique ID.<POINTS> Number of used credits<ERR> Error code

Example:OK:44123123123:80625:0.006;OK:44234234234:80627:0.006;

or

OK:44123123123:80625:0.006;ERROR:4433412333:13;


https://ssl.hqsms.com/api/hlr.do


Returned parameters to script are described in following table:


id* Unique Id of (request-number) which you will get when requesting to us with number

number* Checked number

mcc* Mobile country code

mnc* Mobile network code

info* Name of network or description of error

status* OK when number is correct, FAIL when number is wrong

date* UNIX timestamp when number was checked

ported* 0 number not ported, 1 number ported

ported_from* null when number is not ported or name of network from which number is ported

idx Optional custom value sent with HLR request and sent back in CALLBACK (&idx=123)

*All characters are case sensitive

The list of possible error, which may appear in info field, with description is in Appendix 2 – Errorcodes.

Example return:

Array( [0] => Array ( [id] => 80625 [number] => 48600600600

[mcc] => 260[mnc] => 2[info] => T-Mobile[status] => OK[date] => 1302703609[ported] => 0[ported_from] => null

)

[1] => Array ( [id] => 80627 [number] => 48500600700

[mcc] => 260[mnc] => 2[info] => ABSENT_SUBSCRIBER[status] => FAIL[date] => 1302703609[ported] => 0[ported_from] => null

)

)




17. Last sentence

Phone numbers should be given in 11-digits format (i.e. 48502602702). When national prefix is not given, polish national prefix (48) will be added.

Special characters are these that don't fulfill regular expression: @£$¥èéùìòÇØøÅå_^{}\[~]|ÆæßÉ!"#¤%&'()*+,-./0-9:;<=>?A-ZÄÖÑÜ§¿a-zäöñüà <enter>

ATTENTION! Chars: ^ { } [ ] ~ \ | <enter> according to GSM specificiation are being counted double (when no special characters are in message).

List of special chars that may be changed to normal ones using parameter &normalize:

'normalize_chars' => array('Š'=>'S', 'š'=>'s', 'Ś'=>'S', 'ś'=>'s', 'Đ'=>'Dj', 'đ'=>'dj', 'ź'=>'z', 'ż'=>'z','Ź'=>'Z', 'Ż'=>'Z', 'Ž'=>'Z','ž'=>'z', 'Č'=>'C', 'č'=>'c', 'Ć'=>'C', 'ć'=>'c', 'À'=>'A', 'Ą'=>'A', 'Á'=>'A', 'Â'=>'A', 'Ã'=>'A', 'Ä'=>'A','Å'=>'A', 'Æ'=>'A', 'Ç'=>'C', 'È'=>'E', 'É'=>'E', 'Ę'=>'E', 'ę'=>'e', 'Ê'=>'E', 'Ë'=>'E', 'Ì'=>'I', 'Í'=>'I','Î'=>'I', 'Ï'=>'I', 'Ñ'=>'N', 'Ò'=>'O', 'Ó'=>'O', 'Ô'=>'O', 'Ł'=>'L', 'ł'=>'l', 'Ń'=>'N', 'ń'=>'n', 'Õ'=>'O','Ö'=>'O', 'Ø'=>'O', 'Ù'=>'U', 'Ú'=>'U', 'Û'=>'U', 'Ü'=>'U', 'Ý'=>'Y', 'þ'=>'B', 'ß'=>'Ss','à'=>'a', 'ą'=>'a','á'=>'a', 'â'=>'a', 'ã'=>'a', 'ä'=>'a', 'å'=>'a', 'æ'=>'a', 'ç'=>'c', 'è'=>'e', 'é'=>'e', 'ê'=>'e', 'ë'=>'e','ì'=>'i', 'í'=>'i', 'î'=>'i', 'ï'=>'i', 'ð'=>'o', 'ñ'=>'n', 'ò'=>'o', 'ó'=>'o', 'ô'=>'o', 'õ'=>'o', 'ö'=>'o','ø'=>'o', 'ù'=>'u', 'ú'=>'u', 'û'=>'u', 'ý'=>'y', 'þ'=>'b', 'ÿ'=>'y', 'Ŕ'=>'R', 'ŕ'=>'r',

),

Points charges table:

Without special characters With special or/and polish characters

Characters amount Number of parts Characters amount Number of parts

160 1 SMS 70 1 SMS

306 2 SMS 134 2 SMS

459 3 SMS 201 3 SMS

612 4 SMS 268 4 SMS

765 5 SMS 335 5 SMS

918 6 SMS 402 6 SMS

Attention! The newest SMSAPI technical documentation is always in „POMOC” on our website https://www.smsapi.pl.

CALLBACK requests are being sent from following IP addresses: 62.181.2.52, 62.181.2.58, 31.186.85.46 and 31.186.83.80


https://www.smsapi.pl/


Appendix 1 – Delivery reports list

Status list:

Number STATUS Polish statusnames

Description

401 NOT_FOUND Nieznaleziona Wrong ID or report has expired

402 EXPIRED Przedawniona Messages expired

403 SENT Wysłana Message is sent

404 DELIVERED Dostarczona Message is delivered ro recipient

405 UNDELIVERED Niedostarczona Message is undelivered (invalid number, roaming error etc)

406 FAILED Nieudana Sending message falied – please report it to usB

407 REJECTED Nieznany Message is undelivered (invalid number, roaming error etc)

408 UNKNOWN Kolejka No report (message may be either delivered or not)

409 QUEUED Zaakceptowana Message is waiting to be sent

410 ACCEPTED Ponawianie Message is delivered to operator

Appendix 2 – Error codes

Error codes list:

ERROR Descripction

8 Error in request (Please report)

11 Message too long or there is no message or parameter nounicode is set and special characters (including Polish characters) are used. For VMS messages this error may mean no wave file or tts error text (no text or different than UTF-8 encoding).

12 Message has more parts than defined in &max_parts parameter.

13 Invalid phone number

14 Wrong sender name

17 FLASH message cannot contain special characters

18 Invalid number of parameters

19 Too many messages in one request

20 Invalid number of IDX parameters

21 MMS message is too big (maximum 300kB)

22 Wromg SMIL format

23 Error in importing a file for MMS or VMS messageB

24 Wrong format of imported file

25 Parameters &normalize and &datacoding musn't appear in the same request.

26 MMS subject is to long. Subject may contain up to 30 characters.

27 Too long idx parameter value.

30 Wrong UDH parameter when &datacoding=bin



31 Error in TTS conversion

32 Eco, MMS i VMS messages may be sent only to Polish numbers or sending messages to non-Polish numbers has been disabled (for Pro messages).

33 No Polish mobile phone numbers for ECO sending

35 Wrong tts_lector given. Available values: agnieszka, ewa, jacek, jan, maja

36 Sending binary messages with footer is disallowed.

40 No group with given name in phonebook

41 Chosen group is empty

50 Messages may be scheduled up to 3 months in the future

51 Wrong VMS sent date, VMS messages may be sent only between 8am and 10pm or combination of parameters try and interval may cause sending one oftries after 10pm.

52 Too many requests for one phone number (maximum 10 requests within 60 seconds)

53 Not unique idx value.

54 Wrong date - (only unix timestamp and ISO 8601)

55 No landline numbers in the recipients' list and paremeter skip_gsm set.

56 The difference between date sent and expiration date can't be less than 1 and more tha 12 hours.

57 Phone number is blacklisted.

60 Group of codes with rthis name doesn't exist

61 Group of codes are expired

62 All codes from this group are already used

65 Not enough unused codes in the group. There is fewer codes in the group thatnumbers in request.

66 Parameter [%kod%] the message content is missing. This parameter is necessary for requests with parameter &discount_group.

101 Invalid authorization info

102 Invalid username or password

103 Insufficient credits on Your account

104 No such template

105 Wrong IP address (for IP filter turned on)

110 Service is not available on account (SMS, MMS, VMS or HLR).

200 Unsuccessful message submission

201 System internal error (please report)

202 Too many simultaneous request, message won't be sent

301 Message with provided ID doesn't exist or is scheduled for following 60 seconds (such messages cannot be deleted)

400 Invalid message ID of a status response

999 System internal error (please report)



HLR error's list:

Błąd Opis

UNKNOWN_SUBSCRIBER Invalid, not active number. Error is permanent.

ABSENT_SUBSCRIBER Number turned off or out of range. Number is considered to be inactive but it may change back to active once it is in range. Error is temporary.

TELESERVICE_NOT_PROVISIONED

The recipient has no SMS subscription. Error is permanent.

SYSTEM_FAILURE Temporary network or protocol failure

HLR_LOCAL_CANCEL /HLR_ABORT

Temporary problem or lost reach

CALL_BARRED Barring of the recipients number. Error is permanent.

Appendix 3 - Encoding

Default encoding is windows-1250. However you can set different encoding of messages byadditional parameter &encoding in your HTTP GET request. Available encodings types are:

'iso-8859-1' 'iso-8859-2''iso-8859-3''iso-8859-4''iso-8859-5''iso-8859-7''windows-1250''windows-1251''utf-8'

Example:https://ssl.smsapi.pl/sms.do?username=username&password=password_in_MD5&to=48500000000&encoding=utf-8&message=message_content

Appendix 4 – Example scripts

Sending SMS message using fopen function<?php$username = "username";$password = md5("password");$to = "48502602702";$from = "48502607702";$eco = 1; // 0 – Pro message, 1 – Eco message$message= "my message";

if ($username && $password && $to && $message) { $data = "?username=$username&password=$password&to=$to&eco=$eco&message=$message&from=$from"; $file = fopen('https://ssl.smsapi.pl/sms.do'.$data,'r'); $result = fread($plik,1024); fclose($file); echo $result;}?>



SMS sends from HTML form using PHP.

<?phpif (strlen($_POST['sms_from'])>0 &&strlen($_POST['sms_to'])>=9 &&strlen($_POST['sms_message'])>0) {$username = "login";$password = md5("password");$from = $_POST['sms_from'];$to = $_POST['sms_to'];$message= urlencode($_POST['sms_message']);echo file_get_contents("https://ssl.smsapi.pl/sms.do?"."username=$username&password=$password&to=$to&"."message=$message&from=$from",FALSE,NULL,0,100);}?><html><head><meta http-equiv="Content-type" content="text/html; charset=windows-1250"></head><body><form name="sms" method="POST" action=""><table><tr><td>Od:</td><td><input type="text" name="sms_from" value=""></td></tr><tr><td>Do:</td><td><input type="text" name="sms_to" value=""></td></tr><tr><td>Wiadomość:</td><td><textarea name="sms_message"></textarea></td></tr><tr><td colspan="2"><input type="submit" value="wyślij"></td></tr></table></form></body></html>

MMS sends directly using PHP <?php

$username = 'login';$password = md5('haslo');$to = "48500000000";$subject = urlencode("smsAPI.pl");$smil= '<smil><head><layout><root-layout height="600" width="425"/> <region id="Image" top="0" left="0" height="100%" width="100%" fit="meet"/></layout></head><body><par dur="5000ms"><img src="https://www.smsapi.pl/img/mms.jpg" region="Image"></img></par></body></smil> ';

if ($username && $password) {$data = "?username=$username&password=$password&to=$to&subject=$subject&smil=$smil";$plik = fopen('https://ssl.smsapi.pl/mms.do'.$data,'r');$wynik = fread($plik,1024);fclose($plik);echo $wynik;

}

?>



Example MMS message in SMIL format (MMS sending)<smil>

<head><layout>

<root-layout width="160" height="135"/><region id="Image" width="160" height="114" left="0" top="0"/> //Rozmiar obrazka<region id="Text" width="160" height="20" left="0" top="120"/> //Rozmiar pola tekst.<region id="Audio" width="106" height="1" left="0" top="120"/> //Rozmiar pola audio.

</layout></head><body>

<par dur="0s"><img src="http://adres_www_do_obrazu" region="Image" /> //Adres do obrazka<text src="http://adres_do_pliku_txt" region="Text" /> //Adres do pliku tekstowego<audio src="http://adres_do_pliku_wav" region="Audio" /> //Adres do pliku audio

</par></body>

</smil>

Example of sending VMS message using cURL library<?php

$path_to_file = dirname(__FILE__).'/file.wav';

$ch = curl_init('https://ssl.smsapi.pl/vms.do');

curl_setopt_array($ch, array(CURLOPT_RETURNTRANSFER => 1,CURLOPT_POST => 1,CURLOPT_POSTFIELDS => array(

'username' => 'username','password' => 'md5(password)','to' => '48500500500','file' => '@'.$path_to_file,

)));

$response = curl_exec($ch);

echo $response;

?>



Receiving delivery report (CALLBACK SMS DLR)

<?php

// UWAGA! Poniższy przykład jest tylko poglądowy. Nie sprawdza on danych// wejściowych co jest zalecane dla zmiennych GET: MsgId i status, oraz nie// sprawdza czy zmienne nie są podane przez osoby trzecie. // // W przypadku wysłania z wiadomością parametru idx zostanie on zwrócony $_GET['idx']

if($_GET['MsgId'] && $_GET['status'] ) { mysql_select_db('nazwa_bazy',mysql_connect('localhost','login','haslo')); $arIds = explode(',',$_GET['MsgId']); $arStatus = explode(',',$_GET['status']); $arIdx = explode(',',$_GET['idx']);

if($arIds) foreach($arIds as $k => $v){ mysql_query("UPDATE sms SET sms_status = '".$arStatus[$k]."', sms_index = '”.$arIdx[$k].”' WHERE sms_id='".$v."' LIMIT 1");} mysql_close();

echo “OK”;}

?>

Example of MMS receiving script

<?php$IP = $_SERVER['REMOTE_ADDR'];

$recived=0; foreach($_FILES as $plik) { if(is_uploaded_file($plik['tmp_name'])) { if(move_uploaded_file($plik['tmp_name'],'mms/'.$plik['name'])) { $recived=1; } } } if ($recived == 1) { echo "OK"; }

?>



Example MMS message sent to CALLBACK script (odbiór MMS)

POST: Array( [mms_subject] => Testowy MMS [mms_from] => 48600000000 [mms_to] => 48500000000 [mms_date_recv] => 1256031673 [mms_date] => 1256031643)

FILES: Array( [0] => Array ( [name] => 0.JPG [type] => image/jpeg [tmp_name] => /tmp/phpGXutNv [error] => 0 [size] => 25097 )

[1] => Array ( [name] => 1.txt [type] => text/plain [tmp_name] => /tmp/phpaoM6dU [error] => 0 [size] => 14 )

[2] => Array ( [name] => 3.amr [type] => audio/AMR [tmp_name] => /tmp/php6I0KEi [error] => 0 [size] => 27078 ))



History of changes

Vesrsion Date Changes

Ver 2.29.0 08.11.2013 1. Introducing from parameter for VMS messages sending

Ver 2.28.0 07.10.2013 1. Bulk CALLBACK description introduced.

Ver 2.27.2 04.09.2013 1. Introducing Error code 57

Ver 2.27.1 28.08.2013 1. Introducion of Polish names for delivery statuses (may appear in API responses)

Ver 2.27.0 30.07.2013 1. Introduction of &idx parameter in HLR Lookup service.1. New error 27 which meand too long idx value.

Ver 2.26.0 18.07.2013 1. Introduction of &skip_foreign parameter

Ver 2.25.0 23.04.2013 1. Introduction of discount codes in the API.2. Introduction of &sms2way parameter.3. Introduction of &nofify_url parameter

Ver 2.24.1 05.02.2013 1. HLR errors description introduced.2. Updating list of IP addresses from which callback may be sent.

Ver 2.24.0 19.10.2012 1. Introducing &expiration_date and new Error code 56 corresponding with it.2. Added possibility to change TTS lector in VMS (&tts_lector).3. New error code 110 which means that service (SMS, MMS, VMS or HLR) is not available on sending account4. Introducing new Error code 36.5. Introducing length limit for MMS subject and new Error code 26 corresponding with it.

Ver 2.23.0 13.09.2012 1. Introducing pressed and hanguptime parameters for CALLBACK requests with VMS delivery reports.2. Added parameter &max_parts

Ver. 2.22.0 24.07.2012 1. Introducing &idx and &check_idx for MMS and VMS messages.2. Introducing &idx for CALLBACK requests with MMS and VMS delivery reports.3. Introducing &normalize and new Error code 25 corresponding with it.

Ver. 2.21.0 17.05.2012 1. Introducing new date format allowed (ISO 8601) and new Error code 54 meaning wrong date format.

Ver. 2.20.0 27.03.2012 1. Introducing new API SMS parameter check_idx and new Error code 53 corresponding with it.2. Introducing new API VMS parameter skip_gsm and new Error code 55 corresponding with it.

Ver. 2.19.0 01.03.2012 1. HLR Lookup Description2. Introducing new Error code 52 preventing from looping sending procedure

Ver. 2.18.0 02.02.2012 1. New examples

Ver. 2.17.0 1. Documentation in English

ATTENTION! You can find the newest version of SMSAPI technical documentation in tab „POMOC on our site https://www.smsapi.pl/.


smsapi http en

Documents

multiple sms

sms receiving15

sms delivery confirmation

scheduled sms

sms sending2

messages delivery confirmation

multiple personalized

mms messages receiving15