Documentation for HQSMS (https)

Version 3.5

Documentation HQSMS (https)

Version 3.5

Table of contents
1. Introduction
1.1 How to start
1.2 IP filter for API interface
1.3 API password
2. Single SMS Message sending
2.1 Sending Fast messages (with highest priority)
2.2 Scheduled SMS sending
2.3 Deleting single scheduled messages
3. Bulk SMS sending
3.1 Sending SMS messages to numbers from phonebook group
3.2 Bulk personalized SMS sending using parameters
3.3 Bulk SMS sending using IDX parameter
3.4 Sending messages with cut.li
4. Sending messages using templates
5. mail2SMS Sending SMS using e-mail
7. SMS delivery confirmation receiving CALLBACK procedure
7. HLR lookup
8. Last sentence
Appendix 1 Delivery reports list
Appendix 2 Error codes
Appendix 3 Encoding
Appendix 4 Example scripts
History of changes

ComVision 2015
Page no: 2/21

(In case of any questions please contact us at [email protected])

go to the table of contents

Documentation HQSMS (https)

Version 3.5

1. Introduction
HQSMS is a high quality SMS platform which enables you to integrate any of your applications
with our SMS message sending and receiving 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 HQSMS you need to register and create an account on our website:
URL address: http://www.hqsms.com/
Registration is completely free. Your account is ready to use just after you register, but we recommend
you to verify at least one sender name or number. Every message sent before validation has the
HQSMS 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 SETTINGS API tab IP addresses filter in field IP addresses filter. 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 Settings 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://api.hqsms.com/sms.do for SSL secured connections
- https://api2.hqsms.com/sms.do backup for SSL secured connections
- http://api.hqsms.com/sms.do for standard connections (Unrecommended!)
- http://api2.hqsms.com/sms.do backup for standard connections (Unrecommended!)
Messages should be sent as a HTTP GET or POST request to our system:
Parameter
Description
username *
password *
to
group
message *

from

ComVision 2015
Page no: 3/21

Username used to identify a user in our system

Password to Your account hashed with MD5
Mobile phone number of the recipient (i.e. 44123456789 ).
Name of the group from the phonebook to which message should be sent.
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 3
messages joined together and charged as three messages. Detailed information
about special characters are given in chapter 9.
Name of the sender. As a default the sender name is set to HQSMS. Only verified
names are being accepted (&from=active_name). Sender name may be set after
loging into web panel on api.hqsms.com in SETTINGS SENDER NAMES.

(In case of any questions please contact us at [email protected])

go to the table of contents

Documentation HQSMS (https)

Version 3.5

encoding

This parameter describes the encoding of the message text. UTF-8 is set as default.
If another encoding is needed parameter encoding should have following value:
- for iso-8859-2 (latin2) should be &encoding=iso-8859-2
- for Windows-1250 should be &encoding=windows-1250
flash
Sending a message 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, length and sms count). (&details=1)
date
Date in UNIX timestamp (&date=1287734110) or in ISO 8601 (&date=2012-0510T08: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)
idx
Optional custom value sent with SMS and sent back in CALLBACK (&idx=123).
check_idx
Prevents from sending more than one message with the same idx. When this
parameter is set and message with the same idx was already sent error 53 is
returned.
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. Defaut
value can be set in customers panel.
nounicode
Setting this parameter prevents from sending messages containing special
characters. ERROR: 11 will be returned when the message contains special
characters.
normalize
If message will contain special characters they will be replaced with equivalent (-e,
-n, -y ...).
fast
Setting this parameter to 1 will result in sending message with the highest priority
which ensures the quickest possible time of delivery. Fast messages costs 50%
more than normal message. Attention! Mass and marketing messages mustnt be
sent with fast parameter.
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 15 minutes and more than 48 hours (we recommend using
minimum 1 hour and maximum 12 hours difference). Time will be set with tolerance
+/- 5 minutes.
notify_url
Parameter allows to set CALLBACK URL for message from request. This parameter
may be used when there is no default CALLBACK URL for this user or when it
should be different then default one (notify_url has higher priority than default
callback). ATTENTION! notify_url parameter may be used only for requests with one
numebr, it cannot be used for mass message sending.
*

- 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.

ComVision 2015
Page no: 4/21

(In case of any questions please contact us at [email protected])

go to the table of contents

Documentation HQSMS (https)

Version 3.5

Request:

https://api.hqsms.com/sms.do?
username=username&password=passwordMD5&from=sender_name
&to=44123456789&message=message_content

Response:

OK:<ID>:<POINTS>
or (when error occur)
ERROR:<ERR>

<ID>
<POINTS>
<ERR>
Example:

Message unique ID. You will need it for delivery confirmation

Amount of used credits (i.e. Text sent in 3 messages will return 3xSMS
amount)
Error code (check the error code list in Appendix 2)
OK:17101000090360359:0.055
or
ERROR:102

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

2.1 Sending Fast messages (with highest priority)

Setting parameter fast to 1 (&fast=1) ill result in sending message with the highest priority which
ensures the quickest possible time of delivery. Fast messages costs 50% more than normal message.
Request:

https://api.hqsms.com/sms.do?
username=username&password=passwordMD5&from=sender_name&to
=44123456789&fast=1&message=Fast_message_content

Response:

OK:<ID>:<POINTS>
or (when error occur)
ERROR:<ERR>

<ID>
<POINTS>
<ERR>
Example:

Message unique ID. You will need it for delivery confirmation

Amount of used credits (i.e. Text sent in 3 messages will return 3xSMS
amount)
Error code (check the error code list in Appendix 2)
OK:17101000090360359:0.070
or
ERROR:102

ATTENTION! Mass and marketing messages mustnt be sent with fast parameter. In case of sending
message to more than one recipient in a single request messages will be sent as normal ones, without
parameter &fast=1.
In case of any problems with sending requests to basic URL (as in example above) backup URL may
be used: https://api2.hqsms.com/.

ComVision 2015
Page no: 5/21

(In case of any questions please contact us at [email protected])

go to the table of contents

Documentation HQSMS (https)

Version 3.5

2.2 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.
Request:

https://api.hqsms.com/sms.do?
username=username&password=passwordMD5&to=44123456789&date=
1577878200&message=scheduled_message_content

Response:

OK:<ID>:<POINTS>
or (when error occur)
ERROR:<ERR>

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

2.3 Deleting single scheduled messages

Parameter

Description

username *

Username used to identify a user in HQSMS system.

password *

Password to Your account hashed in MD5

sch_del*

ID of message to delete (returned after sending one).

* - required field

Example nr 1
Request:

https://api.hqsms.com/sms.do?
username=username&password=passwordMD5&
sch_del=09040616088106874

Response:

OK
or (when ID od message doesn't exist)
ERROR:301

Example ID:

09040616088106874

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

ComVision 2015
Page no: 6/21

(In case of any questions please contact us at [email protected])

go to the table of contents

Documentation HQSMS (https)

Version 3.5

ComVision 2015
Page no: 7/21

(In case of any questions please contact us at [email protected])

go to the table of contents

Documentation HQSMS (https)

Version 3.5

3. Bulk SMS sending

Sending messages to a group of recipients is similar to single submission (presented in
chapter 2). The only difference is filling field to with multiple set of recipients numbers. In order to
successfully send this type of message, we recommend to pass all parameters in a HTTP POST
request just to assure that all recipients numbers will be submitted correctly.
If the total cost of sending this message is greater than the number of available credits on
user'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 HQSMS due to wrong
prefix or landline number) than these numbers will be skipped and all other will be sent. Delivery
reports will not concern the skipped numbers. If any number will appear more than once in one
request message will be sent only once to this recipient.
Request:

https://api.hqsms.com/sms.do?
username=username&password=passwordMD5&from=sender_name
&to=48500500500,48501501501,48502502502&message=message

Response:

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

<ID>
<POINTS>

Message unique ID. You will need it for delivery confirmation

Number of used credits (i.e. Text sent in 3 messages will return 3xSMS
amount)
Recipient's phone number

<PHONE>

Example:
OK:17101000090567759:0.055:500500500;OK:171010000903455357:0.055:501500501;
OK:17101000096577326:0.055: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.
In case of any problems with sending requests to basic URL (as in example above) backup URL may
be used: https://api2.hqsms.com/.

ComVision 2015
Page no: 8/21

(In case of any questions please contact us at [email protected])

go to the table of contents

Documentation HQSMS (https)

Version 3.5

3.1 Sending SMS messages to numbers from phonebook group

It is possible to send messages to group of numbers from Phone Book. In order to do that such group
should be first created in web panel menu Phone Book. An example of sending messages to group
from Phone Book is like follows:
Request:

https://api.hqsms.com/sms.do?
username=username&password=passwordMD5&
group=test_goup&message=Test message sent to contacts from
phonebook

Response:

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

<ID>
<POINTS>

Message unique ID. You will need it for delivery confirmation

Number of used credits (i.e. Text sent in 3 messages will return 3xSMS
amount)
Recipient's phone number

<PHONE>

Example:
OK:17101000090567759:0.055:500500500;OK:171010000903455357:0.055:501500501;
OK:17101000096577326:0.055:502502502;
In case of any problems with sending requests to basic URL (as in example above) backup URL may
be used: https://api2.hqsms.com/.

ComVision 2015
Page no: 9/21

(In case of any questions please contact us at [email protected])

go to the table of contents

Documentation HQSMS (https)

Version 3.5

3.2 Bulk personalized SMS sending using parameters

There is possibility to send up to 100 personalized messages in one request using personalization
parameters. To send more personalized messages more than one request have to be used.
Personalization parameters should be defined in request as param1, param2, param3, param4,
which will replace [%1%], [%2%], [%3%] and [%4%] in message content. Values of these parameters
have to be separate by pipe char | according to the template below:
param1=Ann|Michael|Andrew&param2=Smith|Thomas|Davis
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.
Parameters
After defining parameters the may be used in message content:
Parameter
Description
[%1%]

Value of parameter 1 (param1)

[%2%]

Value of parameter 2 (param2)

[%3%]

Value of parameter 3 (param3)

[%4%]

Value of parameter 4 (param4)

Example:
https://api.hqsms.com/sms.do?
username=username&password=passwordMD5&from=sender_name&to=48600111222,
48500111222&message=Message content, parametr1: [%1%] parametr2: [%2%]
&param1=John|Ann&param2=30|40
Message will have following contents:
Message 1 : Message content, parametr1: John parametr2: 30
Message 2 : Message content, parametr1: Ann parametr2: 40
In case of any problems with sending requests to basic URL (as in example above) backup URL may
be used: https://api2.hqsms.com/.

3.3 Bulk SMS sending using IDX parameter

There is possibility to send mass messages with custom parameter IDX different for each message.
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 parameter
value. 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.
In case of any problems with sending requests to basic URL (as in example above) backup URL may
be used: https://api2.hqsms.com/.

ComVision 2015
Page no: 10/21

(In case of any questions please contact us at [email protected])

go to the table of contents

Documentation HQSMS (https)

Version 3.5

3.4 Sending messages with cut.li

This function allows you to use in SMS messages the short URL - http://cut.li, which will redirect the
message recipient on URL which you will add as parameter. In the SMS message, the URL added as
parameter [%goto:adres_url.com%] will be visible eg. as http://cut.li/ABCD (each recipient will
receive unique end of link "/ABCD").
Example:
https://api.hqsms.com/sms.do?
username=username&password=passwordMD5&from=sender_name
&to=49500500500,42501501501,47502502502&message=test message_with_short
link:_[%idzdo:www.smsapi.pl%]_end.
In case of any problems with sending requests to basic URL (as in example above) backup URL may
be used: https://api2.hqsms.com/.

ComVision 2015
Page no: 11/21

(In case of any questions please contact us at [email protected])

go to the table of contents

Documentation HQSMS (https)

Version 3.5

4. Sending messages using templates

Using templates it is very easy to change standard notification messages (ma be used in
shops, internet services, medical clinics etc.) without changing php script that implements SMS
sending.
To use templates You should:
After loging on https://api.hqsms.com/ add template in SMS Settings
Templates
Places which should be replaced by a parameter should be given [%N%] where N is number
between 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 Description
template

Template name

paramN

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

single

If 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: Notify
Template content: Hello [%1%], Your order has been sent. The shipment number is [%2%] You ma y
follow it on our site.
https://api.hqsms.com/sms.do?
username=username&password=passwordMD5&from=sender_name&to=44123456789
&template=Notify&param1=Mark&param2=BG12344423
The content of sent message:
Hello Mark, Your order has been sent. The shipment number i BG12344423 You ma y follow it on our
site.
In case of any problems with sending requests to basic URL (as in example above) backup URL may
be used: https://api2.hqsms.com/

ComVision 2015
Page no: 12/21

(In case of any questions please contact us at [email protected])

go to the table of contents

Documentation HQSMS (https)

Version 3.5

5. mail2SMS Sending SMS using e-mail

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

ATTENTION! Password should be given hashed in MD5

Example:
TO:
SUBJECT:
CONTENT:

[email protected]
username@8456fkty567gb3bg37b357b3457b3457
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.
IMPORTANT! The recipient's number mustnt start with + sign. Parameter message must be at
the end of e-mail.
Sender name (parameter &from=) have to be active.

6. Account balance checking

User's account administration is done by sending HTTP GET or POST request to our system:
Parameter
Description
username *
password *
credits*

Username used to identify a user in our system

API password to Your account hashed with MD5
Enter a value 1
- required field

Request:

https://api.hqsms.com/sms.do?
username=username&password=password_in_md5&credits=1

Response:

Credits: <CREDITS>
or (when error occur)
ERROR:<ERR>

<CREDITS>

number of credits available for this user

Example:

Credits: 100

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

ComVision 2015
Page no: 13/21

(In case of any questions please contact us at [email protected])

go to the table of contents

Documentation HQSMS (https)

Version 3.5

7. SMS delivery confirmation receiving CALLBACK procedure

We offer You possibility to run any available script in the web with callback delivery reports. In
order to use this option please login on our site https://api.hqsms.com and set the Callback address
DLR_SMS in Settings API tab API callback settings.
Example.: http://www.my_site.com/status_update.php
It is important that entered address is a valid address to existing, available script.
After updating message status in HQSMS system the update will be sent to callback script (1 to 5
statuses 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:
Parameter Description
MsgId*

Message ID

status*

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

idx*

Optional parameter send with SMS

donedate*

Date in UNIX timestamp of delivery report

username* Username which sent SMS

points*

Number of used credits

to*

Mobile phone number of the recipient

mcc

Mobile country code

mnc

Mobile network code

*All characters are case sensitive

Script have to return OK (echo OK), otherwise the system will be sending requests every 300
seconds.
CALLBACK requests may be sent from one of following IP addresses: 62.181.2.52, 62.181.2.56,
31.186.85.46 and 31.186.82.159

7. HLR lookup
HLR (Home location Register) is an extent base including different kinds of information about
every working telephone number in GSM. In order to use this option you should request one of
following URL :
- http://api.hqsms.com/hlr.do for standard connections
- https://api.hqsms.com/hlr.do for SSL secured connections
with proper parameters described below. All information about numbers will be sent to address given
on our site https://api.hqsms.com 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:

ComVision 2015
Page no: 14/21

https://api.hqsms.com/hlr.do?
username=username&password=passwordMD5&number=44123123123,
44234234234

(In case of any questions please contact us at [email protected])

go to the table of contents

Documentation HQSMS (https)

Version 3.5

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;
Returned parameters to script are described in following table:
Parameter
Description
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

ComVision 2015
Page no: 15/21

(In case of any questions please contact us at [email protected])

go to the table of contents

Documentation HQSMS (https)

Version 3.5

The list of possible error, which may appear in info field, with description is in Appendix 2 Error
codes.
Example:
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
)
)
Script have to return OK (echo OK), otherwise the system will be sending requests every 300
seconds.
In case of any problems with sending requests to basic URL (as in example above) backup URL may
be used: https://api2.hqsms.com/

ComVision 2015
Page no: 16/21

(In case of any questions please contact us at [email protected])

go to the table of contents

Documentation HQSMS (https)

Version 3.5

8. Last sentence
Special characters are these that don't fulfill regular expression: @$_^{}\[~]|!"#
%&'()*+,-./0-9:;<=>?A-Za-z <enter>
ATTENTION! Chars: ^ { } [ ] ~ \ | <enter> according to GSM specification are being counted double
(when no special characters are in message).
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 HQSMS technical documentation is always in HELP on our website
https://www.hqsms.com/.
CALLBACK requests may be sent from one of following IP addresses: 89.174.81.98, 89.174.81.102,
91.185.184.29, 91.185.185.2 or 185.36.169.252
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',
),

ComVision 2015
Page no: 17/21

(In case of any questions please contact us at [email protected])

go to the table of contents

Documentation HQSMS (https)

Version 3.5

Appendix 1 Delivery reports list

Status list:
Number

STATUS

Description

401

NOT_FOUND

Wrong ID or report has expired

402

EXPIRED

403

SENT

404

DELIVERED

405

UNDELIVERED

406

FAILED

407

REJECTED

Message is undelivered (invalid number, roaming error etc)

408

UNKNOWN

No report (message may be either delivered or not)

409

QUEUED

410

ACCEPTED

412

STOP

Messages expired
Message is sent
Message is delivered to recipient
Message is undelivered (invalid number, roaming error etc)
Sending message failed please report it to us

Message is waiting to be sent

Message is delivered to operator

Appendix 2 Error codes

Error codes list:
ERROR

Description

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.

12

Message has more parts than defined in &max_parts parameter.

13

Lack of valid phone numbers (invalid or blacklisted numbers)

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

25

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

27

Too long IDX parameter. Maximum 255 chars.

30

Wrong UDH parameter when &datacoding=bin

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

52

Too many attempts of sending messages to one number (maximum 10

attempts whin 60s)

53

Not unique idx parameter, message with the same idx has been already sent
and &check_idx=1.

54

Wrong date - (only unix timestamp and ISO 8601)

56

The difference between date sent and expiration date can't be less than 1 and

ComVision 2015
Page no: 18/21

(In case of any questions please contact us at [email protected])

go to the table of contents

Documentation HQSMS (https)

Version 3.5

more tha 12 hours.

70

Invalid URL in notify_url parameter.

72

Parameter notify_url may be used only in requests with one recipient's

number, it cannot be used for mass message sending.

74

Sending date doesn't match date sent restrictions set for the account.

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)

200

Unsuccessful message submission

201

System internal error (please report)

202

Too many simultaneous request, message won't be sent

301

ID of messages doesn't exist

400

Invalid message ID of a status response

999

System internal error (please report)

HLR error's list:

Error

Description

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
HLR_LOCAL_CANCEL /
HLR_ABORT
CALL_BARRED

Temporary network or protocol failure

Temporary problem or lost reach
Barring of the recipients number. Error is permanent.

Appendix 3 Encoding
Default encoding is utf-8. However you can set different encoding of messages by additional
parameter &encoding in your HTTP request. Available encoding 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:

ComVision 2015
Page no: 19/21

(In case of any questions please contact us at [email protected])

go to the table of contents

Documentation HQSMS (https)

Version 3.5

https://api.hqsms.com/sms.do?
username=username&password=passwordMD5&to=48500000000
&encoding=utf-8&message=message_content

Appendix 4 Example scripts

Sending SMS message using fopen function
<?php
$params = array(
'username' => 'your_username',
//username from HQSMS
'password' => 'md-password',
//or 'password' => md5('open-text-password'),
'to'
=> '4412334445566',
//destination number
'from'
=> 'HQSMS.com',
//sender name has to be active
'message' => 'content of message',
//message content
);
if ($params['username'] && $params['password'] && $params['to'] && $params['message']) {
$data = '?'.http_build_query($params);
$plik = fopen('https://api.hqsms.com/sms.do'.$data,'r');
$wynik = fread($file,1024);
fclose($file);
echo $result;
}
?>

Receiving delivery report example (CALLBACK SMS DLR)

<?php
if($_GET['MsgId'] && $_GET['status'] ) {
mysql_select_db('db_name',mysql_connect('localhost','username','password'));
$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 =
'".mysql_real_escape_string($arStatus[$k])."', sms_index =
'".mysql_real_escape_string($arIdx[$k])."' WHERE sms_id
='".mysql_real_escape_string($v)."' LIMIT 1");
}
mysql_close();
echo "OK";
}
?>

ComVision 2015
Page no: 20/21

(In case of any questions please contact us at [email protected])

go to the table of contents

Documentation HQSMS (https)

Version 3.5

History of changes
Version

Changes

Ver. 3.5

1. Change API URL.

2. Introducing sending messages with cut.li

Ver. 3.4.1

1. Introducing new error code 74.

Ver. 3.4.0

1. Introducing &notify_url parameter and new error codes corresponding with it.

Ver. 3.3.0

1. Introducing &expiration_date and new Error code 56 corresponding with it.

2. HLR errors description introduced.
3. Updating list of IP addresses from which callback may be sent.

Ver. 3.2.0

1. New date format allowed (ISO 8601) and new Error code 54 meaning wrong
date format.
2. New parameter &max_parts

Ver. 3.1.0

1. New parameter check_idx and corresponding with it error code 53

introduced.
2. Error code 52 introduced.
3. New parameter group introduced, parameter this allows sending messages
to groups from phonebook.
4. New parameter &normalize and corresponding with it error code 25
introduced.

Ver. 3.0

Specification for new version of service

ATTENTION! You can find the newest version of HQSMS technical documentation in tab Help on
our site http://www.hqsms.com/.

ComVision 2015
Page no: 21/21

(In case of any questions please contact us at [email protected])

go to the table of contents