HTTP (Sophisticated) API for Sending & Receiving SMS

1. Overview

1.1. What is the HTTP API?

The HSL Mobile HTTP (Sophisticated) API allows HTTP-capable applications to hold two-way exchanges with any SMS compatible mobile device on a network reachable by HSL by means of HTTP requests and callbacks.

2. Using the API

There are two versions of the API; the original and an enhanced second version. The operation of the versions is broadly similar though the second version supports a wider range of features.

2.1. General Considerations

Certain aspects of the two API revisions are common between them. These commonalities are as follows:

• The callback parameter’s value must be URL-encoded (special characters such as “/” and “&” are replaced with codes) or you will get an error from the server.
• The callback parameter is used by the system to identify the requesting party and must match an existing URL-to-MSISDN mapping or have the same domain as is specified for your account.
• Instances of the destination parameter  must have a value that is a full international MSISDN and must not include  a “+”, any other international  dialling prefix (e.g. 00 or 010), or any other  non-numeric characters. An example UK number (07712) 345678 should be submitted as 447712345678 (where 44 is the country dialing code for the UK).
• The destination parameter may be repeated multiple times to send to multiple mobiles devices/phones in the same request.
• The API supports HTTP GET and POST operations interchangeably for both versions.

2.2. Using “API version 1” to submit MT traffic

To submit a message to the HTTP API using this mode, you should make a HTTP request that specifies the following set of parameters:

Parameter	Purpose
callback	Specifies the URL that should be called back by means of an HTTP GET request when an MO message arrives.
destination	One or more destination MSISDNs which will have the message sent to them.
message	Message that should be delivered.

An example of a GET URL that fulfils the specification is:

http://gms.haysystems.com:8080/?callback=UR&destination=447123456789&message=text

https://gms.haysystems.com:8081/?callback=URL&destination=447123456789&message=text

It is also possible to use a HTTP POST request with the same parameters and the same encoding rules.

2.2.1. The callback URL

When a mobile originated SMS arrives at the HTTP API, it will make an HTTP request to the client’s system. The URL that it uses for this request is that which was specified in the callback parameter specified previously. This URL will have two special strings replaced to carry the information regarding the incoming SMS, these are “$source$” and “$message$” and they are replaced with the mobile device’s MSISDN and the text of the message respectively. An example callback URL would be:

http://www.abc.com/sms.cgi?src=$source$&msg=$message$

Notes:

• The callback is made as a HTTP POST operation.
• The message content is URL-encoded (UTF-8).

Please note that any callback will only be regarded as having succeeded if an HTTP response code of 200 is received by the gateway.

2.3. Using “API version 2” to submit MT traffic

To submit a message to the HTTP API using this mode, you should make a HTTP request that specifies the following set of parameters:

Parameter	Purpose
callback	Specifies the URL that should be called back by means of an HTTP GET request when an MO message arrives.
destination	One or more destination MSISDNs which will have the message sent to them.
message	The message content. The format of this field should be URL-encoded UTF8. This requirement simply means that, for example, content representable in ISO-8859-1 is conveyed to the gateway in UTF8 but (assuming encoding=ISO-8859-1 is specified) the actual SMS will be coded using ISO-8859-1. In current JDKs, this can be achieved by means of java.net.URLEncoder.encode(string, “UTF8”)
encoding	The SMS character encoding to use when sending the message. Permissible options are: ASCII ISO-8859-1 ISO-8859-15 UCS2

An example of a GET URL that fulfils the specification is:

http://gms.haysystems.com:8080/?callback=http%3A%2F%2Fwww.abc.com%2Fsms.cgi&destination=4478123456789&message=%06%33%06%A1&encoding=UCS2

https://gms.haysystems.com:8081/?callback=http%3A%2F%2Fwww.abc.com%2Fsms.cgi&destination=4478123456789&message=%06%33%06%A1&encoding=UCS2

The message parameter in this case encodes two Arabic characters: س and ڡ (which combine in actual Arabic and on most Arabic-supporting phones).

It is also possible to use a HTTP POST request, with the same parameters and the same encoding rules.

When a request is made, a message ID is returned as the content of the HTTP response the gateway generates. This ID is a long hex-encoded number that the gateway uses to uniquely identify the request.

Notes:

• Any unknown SMS character encodings will default to ASCII and be submitted to SMSC platforms for delivery coded as using the GSM alphabet.
• ASCII, ISO-8859-1 and ISO-8859-9 messages can have a length of up to 160 characters, but will be converted to the GSM alphabet which will lead to some best effort character mappings and the escaping of the following characters: “^ | ~ \ { } [ ] €” – which count as 2 characters.
• UCS2 messages require 16 bits per character and thus have a maximum length of 70 characters per message.

For a definition of the GSM alphabet/character set, please refer to 

2.3.1. The callback URL

The API uses a user-provided URL to pass message delivery status notifications (DSNs) and MO messages to the client systems. The URL that it uses for this request is that which was given in the callback parameter specified previously. This URL should not contain either of the two special strings “$source$” or “$message$” or it will be incorrectly interpreted as an old-style callback by the API. An example callback URL would be:

http://www.abc.com/sms.cgi

 

This callback would be URL encoded for it being used as a parameter in the request. The above example callback URL would therefore appear in the HTTP request as:

http%3A%2F%2Fwww.abc.com%2Fsms.cgi

 

Please note that any callback will only be regarded as having succeeded if an HTTP response code of 200 is received by the gateway.

2.3.1.1. MO message delivery callbacks

As mentioned above, the callback URL is used in two different contexts – the first of which is MO  message delivery. In this usage,  the POST request will specify the following set of parameters:

Parameter	Purpose
type	Specifies the type of callback being made. For MO delivery, this parameter is always set to be “MO”.
sender	The MSISDN of the originator of the message. This will generally be a fully internationally qualified numeric MSISDN, but may be an alphanumeric one or a short-code depending on the originator MSISDN field of the MO SMS.
message	The short message. The message is converted to Unicode and then encoded for transfer as a URL-encoded string using UTF-8 character coding.
encoding	The character coding scheme of the message (as per MO SMS DCS field).

The encoding parameter can be regarded as mostly informational rather than a necessity, though the client is free to convert the message from Unicode back to the specific encoding that is reported

2.3.1.2. Delivery status notification (DSN) callback

When used for DSNs, the POST request will specify the following set of parameters:

Parameter	Purpose
type	Specifies the type of callback being made.  For DSN delivery, this parameter is always set to be “DSN”.
id	The message ID that was originally returned as the content of the response when the message was submitted for delivery
states	The state the message is in. This will be one of: PENDING – The message is en route to its destination. DELAYED – The message has been en route for two minutes but has not yet been delivered. DELAYED_THEN_UNDELIVERABLE – The message could not be delivered before its validity period was exceeded. DELAYED_THEN_DELIVERED – The message was delivered, but only after taking long enough to be counted as delayed. DELIVERED – The message was delivered in less than two minutes. UNDELIVERABLE – The message could not be delivered because of some error that it was possible to determine quickly.
recipient	The MSISDN of the recipient of the original message to which this DSN pertains (each one is treated separately)

The combination of the id and recipient parameters serve to uniquely identify every recipient of every message.

2.3.2. Retry procedures for MO messages

The gateway will attempt to deliver callbacks 10 times, on a decaying retry timescale. The retry delay doubles on each attempt and starts at 10 seconds. This means that attempts will be made to deliver the message:

• immediately
• after 10 seconds
• after 20 seconds
• after 40 seconds
• after 80 seconds (1 minute, 20 seconds)
• after 160 seconds (2 minutes, 40 seconds)
• after 320 seconds (5 minutes, 20 seconds)
• after 640 seconds (10 minutes, 40 seconds)
• after 1280 seconds (21 minutes, 20 seconds)
• after 2560 seconds (42 minutes, 40 seconds)

3. Request error codes

The HTTP return code will indicate the outcome of the attempt to submit a message for delivery. The following table summarises the meaning of each return code:

Code	Meaning
200	Request successful. Delivery will be attempted and a DSN will be returned to the callback address once the message is delivered/found to be undeliverable.
400	Request parameters invalid.
403	IP address from where request is being made is not permitted. Request would cause dynamic allocation of MSISDN but account is not configured for dynamic allocations. Quota error (if using quota-controlled account or prepay account).
404	Callback address not recognised.
500	Temporary service problem.

3. Glossary

HTTP	Hyper Text Transfer Protocol. The Internet protocol upon which the World Wide Web is based. It is generally a connectionless client-server protocol primarily used by clients to retrieve richly formatted documents from servers.
SMS	Short Message Service. A messaging service available to allow mobile users to send and receive messages containing textual and other content.
MO	Mobile Originated. A message created on a mobile device and transmitted from it into the wider communications network.
MT	Mobile Terminated. A message submitted to the gateway and forwarded to a mobile network for delivery to an SMS enabled device.
DSN	Delivery Status Notification. A message or callback generated by the API that informs the client as to the status of a message.

4. Appendix A – GSM Alphabet

See GSM Alphabet page