HTTP (Simple) API for Sending & Receiving SMS

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 secret known to both the application sending the HTTP request and HSL’s server, and other parameters associated with the action. The actual parameters and how the input to the MD5 calculation should be performed are included in the sections below describing the supported actions. The MD5 algorithm is included in various SDKs and programming languages  (C/C++,  Delphi, Java,  JavaScript, PHP, Perl, VB). The MD5 algorithm is defined in http://www.ietf.org/rfc/rfc1321.txt.

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 – ringtone cl – group graphic pg – picture message ol – operator log
content	type = rt <ringing-tone-programming-language> as  in Nokia Smart Messaging Specification for Ringing Tones (hex string); or RTTTL/RTX encoding of ring tone (character string). type = cl, pg or ol <ota-bitmap> as in Nokia Smart Messaging Specification for Graphical Logos and Icons (hex string). Supports OTA, BMP and PBM formats.
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 <text> parameter is provided this is assumed to be NULL (i.e. empty). If no <netct> parameter is provided this is assumed to be “000”. If no <netcn> parameter is provided this is assumed to be “00″.

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.

4.2. Retries when customer server unavailable

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. client-acbd
password	Account password.	String e.g. 1h8g234m5
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 <secret> value used as the input to the MD5 calculation is never exchanged in the HTTP request and is provided to the customer by HSL when the account is first set-up.	Hex string e.g.  85943d91966a91e613b5f936c62bd417
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. 4479123456789 or 4479123456789,4479123456789
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. BrandName
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. 0411241134000+
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. 0411241134000+
text	Short message text in ISO 8859-1.	String e.g. Hello world
message	Short message.	Hex string e.g. 003000310032 or 024A3A6D35A5CDCD29858DADCDBDB804 00B698E2EC517624CB14658936C59661461 6614616814616828DB12658B2CC28C2CC28 C2CC28C2D051B624BA146E0B2D029024C2 5428C2C4497617217628BB12658A32C49B6 2CB30A30B30A30B40A30B4146D8932C5966 14616614616814616828DB125D0A3705968 14812812A14616224BB0000
content	type = rt <ringing-tone-programming-language> as in Nokia Smart Messaging Specification for Ringing Tones (hex string); or RTTTL/RTX encoding of ring tone (character string)   type = cl <ota-bitmap> as in Nokia Smart Messaging Specification for Graphical Logos and Icons  (hex  string). Supports OTA, BMP and PBM formats.   type = pg <ota-bitmap> as in Nokia Smart Messaging  Specification for Graphical Logos and Icons  (hex  string). Supports OTA, BMP and PBM formats.   type = ol <ota-bitmap> as in Nokia Smart Messaging  Specification for Graphical Logos and Icons  (hex  string). Supports OTA, BMP and PBM formats.	Hex string or character string e.g. 024A3A6D35A5CDCD29858DADCDBDB8040 0B698E2EC517624CB14658936C5966146166 14616814616828DB12658B2CC28C2CC28C2 CC28C2D051B624BA146E0B2D029024C2542 8C2C4497617217628BB12658A32C49B62CB3 0A30B30A30B40A30B4146D8932C596614616 614616814616828DB125D0A37059681481281 2A14616224BB0000 or MyTune:d=4,o=5,b=112:b.6,g.6,16f#6,16g6,1 6f#6,8d.6,8e6,p,16e6,16f#6,16g6,8f#.6,8g6,8a 6,b.6,g.6,16f#6,16g6,16f#6,8d.6,8e6,p,16c6,1 6b,16a,16b
netcn	Network code for GSM network	2 x digits e.g. 10
netct	Country code for GSM network	3 x digits e.g. 244
type	rt – ringtone cl – group graphic pg – picture message ol – operator logo	2 x character e.g. rt
esmclass	Message type. Same as for SMPP esm_class parameter	Integer (decimal) e.g. 0
dcs	Indicates data coding scheme and/or message class. Same as for SMPP data_coding parameter in SMPP v3.4	Integer (decimal) e.g. 0
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. 0 – no delivery receipt 1 – delivery receipt requested 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 “id” field in the delivery receipt will contain the  whole message identifier originally returned at the time of message submission. A message that has been delivered will contain the text “stat:DELIVRD” within the delivery receipt. See Receiving SMS section for further information.	Integer (decimal) e.g. 1
scrport	Source port for datagram. See GSM 03.40	Integer (decimal) e.g. 1024
destport	Destination port for datagram. See GSM 03.40	Integer (decimal) e.g. 1024
msgid	Message identifier from previous submission.	Hex string e.g. 12345678abcdef12
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. 2016-02-08T16:22:33+00:00

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. 1 – Pending 2 – Delivered 3 – Expired (validity period reached) 4 – n/a 5 – Undeliverable
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).

¹ Formatted according to Appendix B of the SMPP v3.4 specification.