Web Service SOAP/XML API for Sending SMS

1. Access to HSL Mobile’s SMS Gateway Service

HSL Mobile provides access to its SMS gateway service using the Web Service API defined in this document to enable a customer applications to send SMS to 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 Web Service API for the delivery of messages to mobiles please contact sales@hslmobile.com

1.2. WSDL

The URL for the WSDL of the web service is: 

http://ws.haysystems.com/ws/services/ShortMessageService?wsdl

1.3. Web Service URL

The URLs of the web service are:

http://ws0.haysystems.com/ws/services/ShortMessageService

http://ws1.haysystems.com/ws/services/ShortMessageService

The secure URLs of the web service are:

https://ws0.haysystems.com/ws/services/ShortMessageService

https://ws1.haysystems.com/ws/services/ShortMessageService

2. Example Code

An application can quickly be created with the ability to send SMS using HSL Mobile’s SMS gateway. The following is an extract of the minimum necessary user code in C#/.NET to send a message where “SMS” has been used as the web reference. 

csharp 0 ) && ( result[ 0 ].success ) ) outcome.Text = “Success”; else outcome.Text = “Fail”;]]>

Further code may be found in the  section.

3. Sending SMS

This document includes the methods that can be used to send text messages (Western character sets or Unicode), binary messages and Nokia Smart Messaging content via SMS to phones on networks supported through HSL’s systems. These methods create single or multiple SMS messages depending on the parameters.

Following the set-up of your account the clientId, password and secret parameter values for use with the web service 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 of 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 token parameter.

Password The password is assigned when the account is provisioned by HSL Mobile. It should be noted that this password is passed “in the clear” (unencrypted) when using HTTP. It is recommended that HTTPS be used when using a password.
MD5 

As an alternative to a password an MD5 digest can be included in the parameters submitted with the HTTP request. The secret and parameters are concatenated together to provide the input to the MD5 calculation. The secret is never passed between the application and HSL Mobile “in the clear” – it is used as a seed in the MD5 calculation along with the 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++, C#, Delphi, Java, JavaScript, PHP, Perl, VB). The MD5 algorithm is defined in http://www.ietf.org/rfc/rfc1321.txt.

3.2. Response from methods

The response will indicate the success or failure of the call to the web service method and will be returned in an array (Outcome[] structure) of boolean-string pairs (Outcome structure). The Outcome structure contains the boolean success and an information field info

The boolean success field indicates if the submission of the message to one of the destinations was successful or if it failed. When a successful submission has taken place the message ID(s) of the message(s) being sent to the mobile will be contained in the info parameter. 

If the submission failed the info field may contain a numerical error value (in decimal) as defined in section 5.1.3 of the SMPP v3.4 specification (http://www.smsforum.net). If the clientId and token parameters were incorrect the info field will contain “AUTH” to indicate an authentication failure.

3.3. Methods

3.3.1. sendText – Sending a simple text message

METHOD

sendText

PURPOSE

Submit an SMS text message to the gateway using a simple 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).

80%

PARAMETERS

Parameter                          Purpose
destinationAddress

Mobile telephone number(s)

text Short message text in ISO 8859-1.  If useUCS2 set to true then message text in UCS2.

OPTIONAL PARAMETERS

Parameter Description
validityPeriod The expiration time (absolute or relative) of the message.
sourceAddress Originating address or source address of short message. (Subject to account configuration.)
registeredDelivery Request delivery receipt when message reaches completion.
scheduledDelivery The time (absolute or relative) the message delivery is to be attempted.
useUCS2 Message text is encoded as UCS2 and not ISO 8859-1. Send message as UCS2.
token MD5 input : <secret><text><destinationAddress>

3.3.2. sendSmartMessage – Sending Nokia Smart Messaging SMS

METHOD

sendSmartMessage

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.

80%

PARAMETERS

Parameter                          Purpose
destinationAddress

Mobile telephone number(s)

contentType

rt – ringtone

cl – group graphic

pg – picture message

ol – operator logo

content

contentType = 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).

contentType = 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.

OPTIONAL PARAMETERS

Parameter Description
validityPeriod The expiration time (absolute or relative) of the message.
sourceAddress Originating address or source address of short message. (Subject to account configuration.)
registeredDelivery Request delivery receipt when message reaches completion.
scheduledDelivery The time (absolute or relative) the message delivery is to be attempted.
mnc Network code for GSM network (mandatory for operator logos).
mcc Country code for GSM network (mandatory for operator logos).
text Text message for picture message (where contentType=pg).
token

MD5 input : <secret><contentType><content><text><mcc><mnc><destinationAddress>

Absent parameters in request: If no <text> parameter is provided this is assumed to be NULL (i.e. empty). If no <mcc> parameter is provided this is assumed to be “000”. If no <netcn> parameter is provided this is assumed to be “00”.

3.3.3. sendRaw – Send raw SMS

METHOD

sendRaw

PURPOSE

Submits an SMS to the gateway using a method that is functionally equivalent to the SMPP submit_sm PDU in SMPP v3.4.

80%

PARAMETERS

Parameter                          Purpose
destinationAddress

Mobile telephone number(s)

payload Short message. 

OPTIONAL PARAMETERS

Parameter Description
validityPeriod The expiration time (absolute or relative) of the message.
sourceAddress Originating address or source address of short message. (Subject to account configuration.)
registeredDelivery Request delivery receipt when message reaches completion.
scheduledDelivery The time (absolute or relative) the message delivery is to be attempted.
esm Message type, mode and/or UDHI
dcs Indicates data coding scheme and/or message class.
pid Protocol ID value.
token MD5 input : <secret><payload><destinationAddress> 

3.3.4. sendDatagram – Sending a message

METHOD

sendDatagram

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.

80%

PARAMETERS

Parameter                          Purpose
destinationAddress

Mobile telephone number(s)

payload Message content 

OPTIONAL PARAMETERS

Parameter Description
validityPeriod The expiration time (absolute or relative) of the message.
sourceAddress Originating address or source address of short message. (Subject to account configuration.)
registeredDelivery Request delivery receipt when message reaches completion.
scheduledDelivery The time (absolute or relative) the message delivery is to be attempted.
dcs Indicates data coding scheme and/or message class.
pid Protocol ID value.
sourcePort Source port
destinationPort Destination port
token MD5 input : <secret><payload><destinationAddress> 

4. Parameter Definitions

Parameter Description Type and Example
clientId

Client identifier.

Identifier to uniquely identify your account.

String

e.g. client-abcd

token

Account password or MD5.

MD5 of action fields and secret. Fields used as input to MD5 are listed in action descriptions in the next section.

The <secret> parameter used as the input to the MD5 calculation is never exchanged in the open and is provided

to the client by HSL when service is first provisioned.

String or hex string

e.g.

1h8g234m5

or

85943d91966a91e613b5f936c62bd417

destinationAddress 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 (comma separated for multiple destinations)

e.g.
 4479123456789

or

4479123456789,4479123456789

sourceAddress Originating address or source address of short message. (Support for this parameter is subject to account configuration.) Source TON and NPI will be automatically set.

String (alphanumeric address has max. 11 characters)

e.g. BrandName

validityPeriod

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+

scheduledDelivery

The time (absolute or relative) that message delivery is to be attempted.

Same as for SMPP schedule_delivery_time parameter as in section 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.  If useUCS2 set to true then message text in UCS2.

String (ISO 8859-1) or hex string (UCS2)

e.g. Hello world!

message

Short message.

Hex string

e.g.

003000310032

or

024A3A6D35A5CDCD29858DADCDBDB8
0400B698E2EC517624CB14658936C5
96614616614616814616828DB12658
B2CC28C2CC28C2CC28C2D051B624BA
146E0B2D029024C25428C2C4497617
217628BB12658A32C49B62CB30A30B
30A30B40A30B4146D8932C59661461
6614616814616828DB125D0A370596
814812812A14616224BB0000

 

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.

024A3A6D35A5CDCD29858DADCDBDB8
0400B698E2EC517624CB14658936C5
96614616614616814616828DB12658
B2CC28C2CC28C2CC28C2D051B624BA
146E0B2D029024C25428C2C4497617
217628BB12658A32C49B62CB30A30B
30A30B40A30B4146D8932C59661461
6614616814616828DB125D0A370596
814812812A14616224BB0000

or

MyTune:d=4,o=5,b=112:
b.6,g.6,16f#6,16g6,16f#6,8d.6,
8e6,p,16e6,16f#6,16g6,8f#.6,8g
6,8a6,b.6,g.6,16f#6,16g6,16f#6,
8d.6,8e6,p,16c6,16b,16a,16b

 

mnc Network code for GSM network.

2 x digits

e.g. 10

mcc Country code for GSM network

3 x digits

e.g. 244

contentType

rt – ringtone

cl – group graphic

pg – picture message

ol – operator logo

2 x character

e.g. rt

esm

Message type, mode and/or UDHI

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 value.

Same as for SMPP protocol_id parameter as for SMPP v3.4 / GSM.

Integer (decimal)

e.g. 0

registeredDelivery

Request delivery receipt when message reaches completion.

false – no delivery receipt

true – request delivery receipt

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 received message. See Receiving SMS section for further information.

Boolean

e.g. true

sourcePort

Source port for datagram.

See GSM 03.40.

Integer (decimal)

e.g. 1024

destinationPort

Destination port for datagram.

See GSM 03.40.

Integer (decimal)

e.g. 1024

useUCS Indicates if message is in ISO 8859-1 or UCS2 encoding

Boolean

e.g. true

Note: The SMPP (Short Message Peer to Peer) protocol specifications can be found on this site in the  section.

5. 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.