SMS HTTP(S) API v4.0.2

1. Introduction

The HTTP Bulk Service allows customers to send SMS messages and receive Delivery Reports (DLRs) over the HTTP/HTTPS protocols.

1.1 Integration

PHP: https://github.com/horisen/smsgate-smshttpclient-php

JavaScript: https://github.com/horisen/smsgate-smshttpclient-node

Go: https://github.com/horisen/smsgate-smshttpclient-golang

1.2 Help with formatting special types of messages

HORISEN BULK System helps you to format special types of messages, like concatenated messages and WSI (WAP Service Indication) messages. HORISEN BULK System may split submitted message into several physical SMS messages (concatenated messages) or reject the message because it is too long. Your balance is charged per physical SMS, as described below.

2. Protocol description

This chapter provides information about the supported types of bulk messages and the data flow of the messages and delivery reports.

It also provides information on the types of cases for the delivery status of the messages.

2.1 Types of bulk messages

You can send the following types of messages:

• GSM Text messages
• Unicode Text Messages
• WAP Service Indicators (WSI)

2.2 Data flow of the messages and delivery reports

The message is submitted over HTTP/HTTPS from you to the HORISEN BULK System. When HORISEN BULK System has information about what happened with the delivery of the message (see here), it will send (also over HTTP/HTTPS) an event to you provided Callback DLR URL.

There are four cases:

• Delivered message (DELIVERED)
• Undelivered message (UNDELIVERED)
• Rejected message (REJECTED)
• Buffered (temporary undelivered) message (BUFFERED) followed by final DLR event, delivered (DELIVERED), undelivered (UNDELIVERED) or rejected (REJECTED)

When the message cannot be delivered as fast as possible due to temporary problems and if the DLR mask allows sending buffered events to customers for each delivery attempt, DLR event buffered will be sent to the Callback DLR URL, as described in here. If the DLR mask does not allow sending DLR event buffered to the customer, no notification will be provided until the final event, delivered or undelivered. When the message is delivered (at first attempt or at any latter attempt) DLR event delivered will be sent, as described in here. When the HORISEN BULK System decides that a message cannot be delivered (at first attempt or at any latter attempt or when message validity expires) a DLR event undelivered will be sent, as described in here. When the message is rejected immediately on submission, the customer will be informed using HTTP response about the reason, as described in here. Rejection may also happen later, and the customer will be informed using DLR event rejected.

2.3 Delivered message

When you submit an SMS to HORISEN BULK System the message will be delivered to its destination as fast as possible. When HORISEN BULK System receives a confirmation that the message is delivered it will send DLR Event 1 to Callback DLR URL.

Figure : Data flow for delivered message

2.4 Undelivered message

This case is similar to "Delivered message", but describes failure in delivery. The Callback DLR URL will be invoked with DLR event 2 and reason. No further attempt for delivery will be made. Messages are undelivered if:

• The destination number does not represent an existing mobile phone.
• There is no route to required destination.
• The HORISEN BULK System was not able to deliver a message to phone during validity period (by default 24 hours).
• In case of some other permanent error that makes delivery to mobile phone impossible.

Figure : Data flow for undelivered message

2.5 Rejected message

Messages can be rejected by the HORISEN BULK System if:

• The username/password submitted with the request do not match the one configured for the particular account.
• The account is disabled.
• There are no money in the account.
• The destination is unpermitted for the customer.
• The sender field contains unpermitted characters.
• The parameter format is not correct.
• Some parameters contain unsupported characters by the current DCS. For example parameter text for text message submission.
• Rejection happens immediately on submission, in which case error will be returned to customer with HTTP/HTTPS response on submission request or it can happen later, in which case callback DLR URL will be invoked with DLR event rejected.

Figure : Data flow for rejected message

Figure : Data flow for message that is rejected later, after successful submission.

2.6 Buffered (temporary undelivered) message

If the HORISEN BULK System cannot deliver the message at first attempt and the DLR mask allows sending of buffered messages to the customer, a DLR will be sent to the customer for each attempt with the reason for the temporary failure.

Reasons for temporary failures can be:

• Absent subscriber (subscriber is not within reach of destination network or his phone is offline).
• Mobile phone buffer for SMS is full.
• Any other temporary failures of mobile device or destination mobile network when there is a chance to be resolved within the message validity period.

HORISEN BULK System will stop trying to deliver message if:

• The message is successfully delivered, in which case DLR event delivered is sent.
• A permanent error happened which makes delivery impossible (e.g. destination number does not exist). DLR event undelivered is sent.
• The Message validity period expired – within 24 hours the HORISEN BULK System was not able to deliver a message to mobile phone. DLR event undelivered is sent.

Figure : Data flow for buffered (temporary undelivered) message

3. Sending SMS

3.1 Text messages in GSM Encoding

SMS to be sent is encoded in JSON document:

{
    "type":"text",
    "auth": {"username":"testuser", "password":"testpassword"},
    "sender":"BulkTest",
    "receiver":"4179123456",
    "dcs":"GSM",
    "text":"This is test message",
    "dlrMask":19,
    "dlrUrl":"http://my-server.com/dlrjson.php"
}

and it has to be submitted to URL:

• For HTTP:

  http://sms.horisen.info:12020/bulk/sendsms

• For HTTPS:

  https://sms.horisen.info:12021/bulk/sendsms

3.2 Examples (from bash shell)

For HTTP:

CONTENT='{
    "type":"text", 
    "auth": {"username":"testuser", "password":"testpassword"}, 
    "sender":"BulkTest", 
    "receiver":"41787078880", 
    "dcs":"GSM", 
    "text":"This is test message", 
    "dlrMask":19, 
    "dlrUrl":"http://my-server.com/dlrjson.php"
}'

curl -L "http://sms.horisen.info:12020/bulk/sendsms" -XPOST -d "$CONTENT"

For HTTPS:

CONTENT='{
    "type":"text", 
    "auth": {"username":"testuser", "password":"testpassword"}, 
    "sender":"BulkTest", 
    "receiver":"41787078880", 
    "dcs":"GSM", 
    "text":"This is test message", 
    "dlrMask":19, 
    "dlrUrl":"http://my-server.com/dlrjson.php"
}'

curl -L "https://sms.horisen.info:12021/bulk/sendsms" -XPOST -d "$CONTENT"

3.3 Unicode Messages

{
    "type":"text",
    "auth": {"username":"testuser", "password":"testpassword"},
    "sender":"BulkTest",
    "receiver":"4179123456",
    "dcs":"UCS",
    "text":"This is test message with some UTF-8 characters üöä€ ",
    "dlrMask":19,
    "dlrUrl":"http://my-server.com/dlrjson.php"
}

3.4 WAP Server Indication (WSI) messages

{
    "type":"wsi",
    "auth": {"username":"6666_TESTHTTP", "password":"TerWAvAs"},
    "sender":"BulkTest", 
    "receiver":"41787078880",
    "url":"https://www.horisen.com/en/",
    "title":"HORISEN", 
    "dlrMask":19,
    "dlrUrl":"http://my-server.com/dlrjson.php"
}

3.5 HTTP Response when sending SMS

If the message is accepted to be sent, HTTP status code is 202 and JSON response is:

{
    "msgId": "9325d0a8-2638-11e6-afe7-bffc7cc8fa4f",
    "numParts": 2
}

If the message is rejected, HTTP status code is 420 and response is:

{
    "error": {
        "code": "107",
        "message": "Invalid sender"
    }
}

The System may also return other error codes from 5xx range. In this case there is no JSON response and error codes conform to standard HTTP error codes.

3.6 Error codes

The available error codes are listed in the table below:

Error code	Value	Description
RC_APPLICATION_ERROR	101	Internal application error.
RC_ENCODING_ERROR	102	Encoding not supported or message not encoded with given encoding.
RC_NO_ACCOUNT	103	No account with given username/password.
RC_IP_NOT_ALLOWED	104	Sending from clients IP address not allowed.
RC_THROTTLING_ERROR	105	Too many messages submitted within short period of time. Resend later.
RC_BLACKLISTED_SENDER	106	Sender contains words blacklisted on destination.
RC_INVALID_SENDER	107	Sender contains illegal characters.
RC_MESSAGE_TOO_LONG	108	Message (not split automatically by HORISEN BULK Service, but by customer) is too long.
RC_BAD_CONTENT_FORMAT	109	Format of text/content parameter is wrong.
RC_MISSING_MANDATORY_PARAMETER	110	Mandatory parameter is missing.
RC_UNKNOWN_MESSAGE_TYPE	111	Unknown message type.
RC_BAD_PARAMETER_VALUE	112	Format of some parameter is wrong.
RC_NO_CREDIT	113	No credit on account balance.
RC_NO_ROUTE	114	No route for given destination.
RC_CONCAT_ERROR	115	Message cannot be split into concatenated messages (e.g. too many parts will be needed).

3.7 How to handle errors

When you receive HTTP status code 420 (METHOD_INVOCATION_FAILURE), do not retry submission of the message, except in case of RC_THROTTLING_ERROR. When multiple receivers are submitted, and there needs to be resubmission, you need to resubmit only to receivers for which an error is reported.

3.8 Throttling error

In case that submission failed with RC_THROTTLING_ERROR, you should wait one second and then resubmit.

3.9 Internal server error

In case the submission failed with HTTP status code 500, INTERNAL_SERVER_ERROR, you should wait at least one minute before resubmitting.

3.10 Receiving DLR

Delivery reports are sent to customer to URL (dlrUrl) provided in JSON with SMS. It is JSON encoded, with the following form:

{
    "msgId": "9325d0a8-2638-11e6-afe7-bffc7cc8fa4f",
    "event": "DELIVERED", 
    // other values are "UNDELIVERED", "REJECTED", "BUFFERED", "SENT_TO_SMSC"
    "errorCode": 0,
    "errorMessage": "if exists",
    "partNum": 1, // range [0..numParts-1]
    "numParts": 2,
    "accountName": "testuser"
}

3.11 DLR Error codes

The supported DLR error codes are given below:

Value (dec)	Description
0	No error
1	Unknown subscriber
9	Illegal subscriber
11	Teleservice not provisioned
13	Call barred
15	CUG reject
19	No SMS support in MS
20	Error in MS
21	Facility not supported
22	Memory capacity exceeded
29	Absent subscriber
30	MS busy for MT SMS
36	Network/Protocol failure
44	Illegal equipment
60	No paging response
61	GMSC congestion
63	HLR timeout
64	MSC/SGSN_timeout
70	SMRSE/TCP error
72	MT congestion
75	GPRS suspended
80	No paging response via MSC
81	IMSI detached
82	Roaming restriction
83	Deregistered in HLR for GSM
84	Purged for GSM
85	No paging response via SGSN
86	GPRS detached
87	Deregistered in HLR for GPRS
88	The MS purged for GPRS
89	Unidentified subscriber via MSC
90	Unidentified subscriber via SGSN
112	Originator missing credit on prepaid account
113	Destination missing credit on prepaid account
114	Error in prepaid system
500	Other error
988	MNP Error
989	Supplier rejected SMS
990	HLR failure
991	Rejected by message text filter
992	Ported numbers not supported on destination
993	Blacklisted sender
994	No credit
995	Undeliverable
996	Validity expired
997	Blacklisted receiver
998	No route
999	Repeated submission (possible looping)

3.12 Delivery report events

The delivery events that HORISEN BULK System sends are:

• DELIVERED (dlr mask 1): Delivered to phone, final status
• UNDELIVERED (dlr mask 2): Non-Delivered to Phone, final status
• BUFFERED (dlr mask 4): Queued on SMSC, temporary status
• SENT_TO_SMSC (dlr mask 8): Delivered to SMSC, temporary status
• REJECTED (dlr mask 16): Non-Delivered to SMSC, final status

Statuses marked with ‘final status’ are final delivery reports – no further delivery reports will be sent for message. Statuses with ‘temporary status’ are of two kinds:

• Queued on SMSC usually means that there was some problem delivering the message to the mobile phone, and further DLRs will follow.
• Queued on SMSC means that HORISEN BULK System sent the message to the destination network.

DLR Mask set for each sent message can be combination of these values. For example, 1+2+16=19 means that all the final statuses will be reported (DELIVERED, UNDELIVERED, REJECTED). DLR Mask 19 is recommended.

4. Additional tables

4.1 GSM character set

Dec		0	16	32	48	64	80	96	112
	Hex	0	10	20	30	40	50	60	70
0	0	@	Δ	SP	0	¡	P		p
1	1	£	_	!	1	A	Q	a	q
2	2	$	Φ	“	2	B	R	b	r
3	3	¥	Γ	#	3	C	S	c	s
4	4	è	Λ	¤	4	D	T	d	t
5	5	é	Ω	%	5	E	U	e	u
6	6	ù	Π	&	6	F	V	f	v
7	7	ì	Ψ	‘	7	G	W	g	w
8	8	ò	Σ	(	8	H	X	h	x
9	9	Ç	Θ	)	9	I	Y	i	y
10	A	LF	Ξ	*	:	J	Z	j	z
11	B	Ø	<ESC>	+	;	K	Ä	k	ä
12	C	ø	Æ	,	<	L	Ö	l	ö
13	D	CR	æ	-	=	M	Ñ	m	ñ
14	E	Å		.	>	N	Ü	n	ü
15	F	å	É	/	?	O	§	o	à

Additional characters on GSM phones (in conversion to GSM character set counted as two characters):

You want to send ASCII	Send the following
Character	Decimal	Hex	Characters	Hex	Decimal
€			<ESC> e	1B 65	27 101
<FF>	10	0C	<ESC> <LF>	1B 0A	27 10
[	91	5B	<ESC> <	1B 3C	27 60
\	92	5C	<ESC> /	1B 2F	27 47
]	93	5D	<ESC> >	1B 3E	27 62
^	94	5E	<ESC> ^	1B 14	27 20
{	123	7B	<ESC> (	1B 28	27 40
|	124	7C	<ESC> @	1B 40	27 64
}	125	7A	<ESC> )	1B 29	27 41
~	126	7E	<ESC> =	1B 3D	27 61

4.2 Supported characters in alphanumeric sender

Special characters:

Special Characters
Supported		Not Supported
Character	ASCII Code	Character	ASCII Code
SPACE	0×20	$	0×24
!	0×21	@	0×40
“	0×22	[	0x5B
#	0×23	\	0x5C
%	0×25	]	0x5D
&	0×26	^	0x5E
‘	0×27	_	0x5F
(	0×28	`	0×60
)	0×29	{	0x7B
*	0x2A	|	0x7C
+	0x2B	}	0x7D
,	0x2C	~	0x7E
-	0x2D	€
.	0x2E
/	0x2F
:	0x3A
;	0x3B
<	0x3C
=	0x3D
>	0x3E
?	0x3F

Supported letters and digits

• 0123456789
• abcdefghijklmnopqrstuvwxyz
• ABCDEFGHIJKLMNOPQRSTUVWXYZ