HTTP (Simple) API for Sending & Receiving SMS
Contents
- HTTP (Simple) API for Sending & Receiving SMS
- 1. Access to HSL Mobile’s SMS Gateway Service
- 2. Example Code
- 3. Sending SMS
- 3.1. Security and authentication
- 3.2. Response from actions
- 3.3. Actions
- 4. Receiving SMS
- 5. Parameter Definitions
- 6. Delivery Receipts
1. Access to HSL Mobile’s SMS Gateway Service
HSL Mobile provides access to its SMS gateway service using the HTTP API defined in this document to enable customer applications to send SMS to mobiles, receive delivery confirmation for SMS sent to mobiles and receive SMS from mobiles. In order to use the API in this document it is necessary to have an account with HSL Mobile.
1.1. Obtaining an account
To open an account to use the HTTP API please contact sales@hslmobile.com.
2. Example Code
Code can be found in the Examples section of developers.hslmobile.com.
3. Sending SMS
This document includes the actions that can be used to send text messages (western character sets or unicode), binary messages and Nokia Smart Messaging content using SMS to mobiles on networks supported by the service. These actions create single or multiple SMS messages depending on the parameters.
A regular HTTP POST or GET can be used by a customer’s application to perform an action to, for example, send an SMS message using the HTTP API. The parameters necessary for each action are shown in the following table (M â mandatory; O â optional):
Parameter | Action | |||||
---|---|---|---|---|---|---|
sendtxt |
sendnok |
submitsm |
senducs |
senddgram |
querysm |
|
clientid |
M | M | M | M | M | M |
password/key |
M | M | M | M | M | M |
destaddr |
M | M | M | M | M | |
srcaddr |
O | O | O | O | O | |
validity |
O | O | O | O | O | |
scheduled |
O | O | O | O | O | |
text |
M | O | ||||
message |
M | M | M | |||
content |
M | |||||
netct |
O* | |||||
netcn |
O* | |||||
type |
M | |||||
esmclass |
O | |||||
dcs |
O | O | ||||
pid |
O | O | ||||
regdeliv |
O | O | O | O | O | |
srcport |
O | |||||
destport |
O | |||||
msgid |
M |
* Mandatory for operator logo.
The URL that is used has the following format:
false
http://<server>[:<port>]/<action>/Â
false
https://<server>[:<port>]/<action>/
(secure HTTP)
Following the set-up of your account the actual server
, port
, clientid
, password
 and secret
 for use in the actions will be provided by HSL.
3.1. Security and authentication
The encryption of communication between the application making the request and HSL Mobileâs systems is achieved through HTTPS.
There are two methods available to the application for authenticating when using HTTP or HTTPS: password or MD5. Either the password or the MD5 method MUST be used when submitting a HTTP request and are passed in the password
 or key
 parameter respectively.
Password | A password is included in the parameters (the password parameter) submitted with the HTTP request. The password is assigned when the account is provisioned by HSL. It should be noted that this password is passed âin the clearâ (unencrypted) when using HTTP. If HTTPS is used the password will be encrypted. |
MD5 | An MD5 message digest is included in the parameters (the key parameter) submitted with the HTTP request. The secret and parameters are concatenated together to provide the input to the MD5 calculation. Note that the secret is never passed between the application and HSL âin the clearâ â it is used as a seed in the MD5 calculation along with other parameters.
The MD5 âmessage digestâ is a 16-byte output calculated from a |
The IP address of the application making the HTTP request can optionally be checked against the customer’s account details. Requests coming from an application connecting from an IP address other than that setup in an account will be rejected. IP addresses for applications authorised to make use of a customer’s account must be provided to HSL Mobile so that they can be entered into the account configuration.
3.2. Response from actions
After an action has been sent using HTTP(S) by the customer application, the action will be performed and a response given back to the customer’s application. The response given will indicate the success or failure of the request and will be returned within the body (or data part) of the HTTP response.
The âFAIL AUTH
â response indicates that your clientid
 and password
 or clientid
 and key
 combination are incorrect, or that the IP address from where the HTTP request is being made is not permitted (if restriction of IP addresses is set-up for the account).
false
response = [ success-response | failure-response ]*
false
success-response = SUCCESS
[<SP> message-id]*
false
message-id = {string of up to 64 printable characters}
false
failure-response = FAIL
[<SP> AUTH
| <SP> error]
false
error = {value indicating the error code returned from the transaction as defined in section 5.1.3 of the SMPP v3.4 specification}
3.3. Actions
3.3.1. sendtxt – Sending a simple text message
PURPOSE
Submit an SMS text message to the gateway using a simple HTTP request. A message that exceeds 160 characters will be split into multiple SMS and a UDH containing segmentation and reassembly information will be added (concatenated SMS).
PARAMETERS
Parameter | Description |
---|---|
destaddr |
Mobile telephone number(s) |
text |
Short message text in ISO-8859-1 |
scheduled |
The time (absolute or relative) the message delivery is to be attempted |
validity |
The expiration time (absolute or relative) of the message |
srcaddr |
Originating address or source address of short message (subject to account configuration) |
regdeliv |
Request delivery receipt when message reaches completion |
key |
<secret><text><destaddr> |
3.3.2. sendnok – Sending Nokia Smart Messaging SM
PURPOSE
Send Nokia Smart Messaging ringtones, operator logos, group graphics (CLI icons) and picture messages.
This action will produce a single or multiple SMS messages containing the content. The necessary segmentation and reassembly information will be included in the SMS messages that are produced for messages that require more than one SMS.
PARAMETERS
Parameter | Description |
---|---|
destaddr |
Mobile telephone number(s) |
type |
rt â ringtonecl â group graphicpg â picture messageol â operator log |
content |
type = rt
type =
|
netcn |
Network code for GSM network (mandatory for operator logos) |
netct |
Country code for GSM network (mandatory for operator logos) |
text |
Text message for picture message (where type=pg) |
key |
<secret><type><content><text><netct><netcn><destaddr>
Absent parameters in HTTP request: If no |
3.3.3. submitsm – Send raw SMS
PURPOSE
Submits an SMS to the gateway using a method that is functionally equivalent to SMPP submit_sm PDU in SMPP v3.4.
PARAMETERS
Parameter | Description |
---|---|
destaddr |
Mobile telephone number(s) |
message |
Short message |
esmclass |
Message type |
dcs |
Data coding scheme and/or message class |
pid |
Protocol ID |
scheduled |
The time (absolute or relative) the message delivery is to be attempted |
validity |
The expiration time (absolute or relative) of the message |
srcaddr |
Originating address or source address of short message (subject to account configuration) |
regdeliv |
Request delivery receipt when message reaches completion |
key |
<secret><message><destaddr> |
3.3.4. senducs – Sending multi-byte text messages (UCS2)
PURPOSE
Send a text message using UCS2 character encoding using a simple HTTP request. A message that exceeds 70 UCS2 characters will be split into multiple SMS and a UDH containing segmentation and reassembly information will be added (concatenated SMS).
This action allows messages composed of unicode characters (includes Arabic, Chinese, Greek characters) to be sent using SMS.
PARAMETERS
Parameter | Description |
---|---|
destaddr |
Mobile telephone number(s) |
message |
Short message text in unicode format using UCS2 data coding |
scheduled |
The time (absolute or relative) the message delivery is to be attempted |
validity |
The expiration time (absolute or relative) of the message |
srcaddr |
Originating address or source address of short message (subject to account configuration) |
regdeliv |
Request delivery receipt when message reaches completion |
key |
<secret><message><destaddr> |
3.3.5. senddgram – Sending a message
PURPOSE
Send a message payload via SMS. A message that exceeds 160 characters or 140 octets will be split into multiple SMS and a UDH containing segmentation and reassembly information will be added (concatenated SMS). This action could be used to send a WAP push message or other similar content.
PARAMETERS
Parameter | Description |
---|---|
destaddr |
Mobile telephone number(s) |
message |
Message Content |
scheduled |
The time (absolute or relative) the message delivery is to be attempted |
validity |
The expiration time (absolute or relative) of the message |
srcaddr |
Originating address or source address of short message (subject to account configuration) |
regdeliv |
Request delivery receipt when message reaches completion |
srcport |
Source port |
destport |
Destination port |
dcs |
Indicates data coding scheme and/or message class |
pid |
Protocol ID |
key |
<secret><message><destaddr> |
3.3.6. querysm – Query the delivery status of a message
PURPOSE
Queries the status of a message that was previously submitted using one of the other actions contained in this document.
PARAMETERS
Parameter | Description |
---|---|
msgid |
Message identifier of previously submitted message. |
key |
<secret><msgid> |
4. Receiving SMS
The HTTP API allows SMS received using a Virtual Mobile Number (VMN) or Virtual SIM (VSIM) on a customer’s account to be relayed to the customer’s application. Received SMS are relayed by HSL’s systems calling a URL that has been supplied by the customer. This URL can be a PHP, ASP, Java servlet or other page and can be used to process inbound SMS received by the VMN or VSIM.
Delivery receipts for messages sent using the HTTP API can also be received (see section 6 for URL parameters).
4.1. URL parameters
When an SMS is received a HTTP or HTTPS request is made by HSLâs systems to relay the mobile number receiving the SMS (recipient), the SMS message content (message
) and the mobile number of the sender of the message (mobileno
).
The following parameters are passed to the customer in the HTTP or HTTPS GET call to the customer’s URL:
Parameter | Definition |
mobileno |
Mobile number of sender. This will be in international format, starting with the digits of the country code. |
message |
Message text. |
recipient |
Mobile number receiving message (e.g. VMN or VSIM). This will be in international format, starting with the digits of the country code. |
charset |
Character set of message ISO8859-1 (default), binary or UCS2 . This parameter may be omitted in the request. When this is the case the character set of the message is ISO8859-1 . |
esm |
Message type. |
pid |
Protocol ID. Note: in hexadecimal. |
dcs |
Data coding scheme and/or message class. Note: in hexadecimal. |
gsm_message |
GSM message. |
scts |
Service Centre Time Stamp of the received message. This is the date and time that the mobile user’s network received the message from the user. |
The default behaviour is for HSLâs systems to attempt delivery for up to 4 hours if your URL is not reachable or is not responding correctly when we relay a received SMS. After this period of time the received message will not be retried and will be deleted.
In order for HSLâs systems to determine that your server has successfully received the SMS from our systems a HTTP â200â response must be given by your server. On receiving this response from a call to your URL our servers will not reattempt delivery of the message to your servers.
Both a primary and secondary URL can be provided for your servers so that if HSL’s systems are unsuccessful in delivering a message to the primary URL, then the secondary URL will then be attempted.
4.3. Message encoding
The <message
> parameter will be URL encoded for transport over HTTP. This means that you can expect all non-printable and special characters to be represented by the character sequence â%nnâ where nn is the hexadecimal value of the character. It is necessary to decode the received message prior to further processing of the message.
For example, the message âHello world
â would be encoded as âHello%20world
â where %20
 represents the space character. In ISO 8859-1 the space character has value 0x20 (32 decimal).
4.4. Redirects
HTTP redirects (response code “3xx”) are not supported and will therefore not be followed. Any response other than a HTTP “200” will be regarded as a failed attempt to deliver the received message.
5. Parameter Definitions
Parameter | Description | Type and example |
---|---|---|
clientid |
Unique identifier for your account. | String
e.g. |
password |
Account password. | String
e.g. |
key |
MD5 of action parameter values and secret. Parameter values used as input to MD5 are listed in the action descriptions in the next section.
The |
Hex string
e.g. |
destaddr |
Mobile telephone number(s) in international format starting with first digit of country code. More than one number can be specified by separating each number by a comma. Destination TON of âinternationalâ and NPI of âE.164â automatically selected. | Digits
e.g. |
srcaddr |
Originating address or source address of short message (support is subject to account configuration) .
Source TON and NPI will be automatically set. |
String (alphanumeric address has max. 11 characters) e.g. |
validity |
The expiration time (absolute or relative) of the message.
Same as for SMPP validity_period parameter as in section 7.1 of the SMPP v3.4 specification. Alternatively, HTTP absolute date format supported. |
String
e.g. |
scheduled |
The time (absolute or relative) that message delivery is to be attempted.
Same as for SMPP schedule_delivery_time parameter as insection 7.1 of the SMPPÂ v3.4 specification. Alternatively, HTTP absolute date format supported |
String
e.g. |
text |
Short message text in ISO 8859-1. | String
e.g. |
message |
Short message. | Hex string
e.g. or
|
content |
type = rt
type =
type =
type =
|
Hex string or character string
e.g.
or
|
netcn |
Network code for GSM network | 2 x digits
e.g. |
netct |
Country code for GSM network | 3 x digits
e.g. |
type |
rt â ringtonecl â group graphicpg â picture messageol â operator logo |
2 x character
e.g. |
esmclass |
Message type.
Same as for SMPP esm_class parameter |
Integer (decimal)
e.g. |
dcs |
Indicates data coding scheme and/or message class.
Same as for SMPP data_coding parameter in SMPP v3.4 |
Integer (decimal)
e.g. |
pid |
Protocol ID.
Same as for SMPP protocol_id parameter as for SMPP v3.4 / GSM |
Integer (decimal)
e.g. 0 |
regdeliv |
Request delivery receipt when message reaches completion.
Delivery receipts will be returned to the same URL as used when receiving inbound SMS. The format of the receipt is as in Appendix B of the SMPP v3.4 specification. Note the â A message that has been delivered will contain the text â |
Integer (decimal)
e.g. |
scrport |
Source port for datagram.
See GSM 03.40 |
Integer (decimal)
e.g. |
destport |
Destination port for datagram.
See GSM 03.40 |
Integer (decimal)
e.g. |
msgid |
Message identifier from previous submission. | Hex string
e.g. |
scts |
Service Centre Time Stamp in ISO 8601 format. Indicates the date and time the message was received from the mobile user by their network.
Note: This parameter is not provided by default and must be enabled. Contact HSL Support to request. <YYYY>-<MM>-<DD>T<HH>:<MM>:<SS>Âą<hh>:<mm> |
String:
e.g. |
6. Delivery Receipts
Receipts will be returned indicating the outcome of a sent message as a result of setting the <regdeliv>
 parameter when the message was submitted.
Parameter | Description |
---|---|
type |
Indicates that the request represents a delivery receipt. Type will be “notif “. |
msgid |
Message identifier of previously submitted message. |
status |
State of delivery outcome.
|
error |
Error code associated with delivery outcome. |
message |
Delivery receipt 1 |
mobileno |
Mobile number to which receipt relates. |
recipient |
Source address used for receipt. |
esm |
ESM class (ignore). |
1Â Formatted according to Appendix B of the SMPP v3.4 specification.