Web Service SOAP/XML API for Sending SMS
Contents
- Web Service SOAP/XML API for Sending SMS
- 1. Access to HSL Mobile’s SMS Gateway Service
- 2. Example Code
- 3. Sending SMS
- 4. Parameter Definitions
- 5. Glossary
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.
SMS.ShortMessageService sms = new SMS.ShortMessageService();
SMS.Outcome[] result = sms.sendText( "acc80964", "5611e621", "447123456789", "Hello World", null );
if ( ( result.Length > 0 ) && ( result[ 0 ].success ) )
outcome.Text = "Success";
else
outcome.Text = "Fail";]]>
Further code may be found in the Examples 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 specification v3.4. 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).
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.
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.
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.
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. 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
|
| 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. |
Hex string or character string e.g. 024A3A6D35A5CDCD29858DADCDBDB8 or MyTune:d=4,o=5,b=112:
|
| 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
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. |