HTTP (Simple) API for Sending & Receiving SMS

Contents

3HTTP.*

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  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
scraddr 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 serverportclientidpassword 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
scraddr

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
scraddr

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
scraddr

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

scraddr 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).

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