HTTP (Sophisticated) API forĀ Sending & Receiving SMS
Contents
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:
|
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:
– The message is en route to its destination.
– The message has been en route for two minutes but has not yet been delivered.
– The message could not be delivered before its validity period was exceeded.
– The message was delivered, but only after taking long enough to be counted as delayed.
– The message was delivered in less than two minutes.
– 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