SMS Gateway
Interface Description
HTTP v1.0

Document nameHTTP v1.0
Document numberEJR10001SIS
Revision1.17
AuthorMartin Kristell
Date2016-05-10
Information classOpen Information
ReviewerJonas Rexeke
Review date2016-05-10
CompanySPIRIUS AB
VAT/REG number556788-4183
Postal addressBox 67
371 21 KARLSKRONA
Telephone number+46 (455) 65 55 00
Fax number+46 (455) 65 55 19
Home pagewww.spirius.com

© Copyright SPIRIUS AB 2018

The contents of this document are subject to revision without notice due to continued progress in methodology, design and manufacturing. SPIRIUS AB shall have no liability for any error or damages of any kind resulting from use of this document.

1. Introduction

1.1 Scope

This section describes the HTTP Interface. It describes the basics of how to use the HTTP Interface (from now on referred to as ‘Interface’) and provides a list of available parameters.

This section is intended for application developers and/or integrators. Basic knowledge of the HTTP1protocol is assumed.

2. HTTP Interface

2.1 Mobile Terminated Messages

2.1.1 Usage

To send a message using the interface, the client creates and sends a HTTP request containing both login credentials and information regarding sender, the actual message and its recipient(s). The fact that login credentials are used in every single request eliminates the need of separate login and logout requests to setup and tear down sessions. The URL is constructed using the server hostname and ports given below together with this path:

cgi-bin/sendsms

Upon reception of the request validates the credentials and parameters. If all checks are passed responds with a “202 Accepted” and then proceeds to send the message to the given mobile subscriber. Should there be anything wrong with the request, it will be rejected and a response is sent back to the client indicating the nature of the error, please see section of Response codes below.

If a delivery report is requested, a request will be sent from SMS Gateway to the client indicating the outcome of the message. SMS Gateway will authenticate itself using a username and a password, if such credentials have been previously configured for the client.

It’s recommended that the client uses SSL-encryption to secure the connection. If desired, SMS Gatewaycan also use SSL-encryption when sending delivery reports back to the client.

2.1.2 Parameters

The table below lists available parameters for MT-messages. Parameters not marked as ‘Mandatory’ can be left out of the request. Other parameters must be present or the request will be rejected.

All parameters must be URI encoded2.

NameMandatoryDescriptionExample
UserYesUsername of client.User=myuser
PassYesPassword of client.Pass=mypassword
ToYesRecipient of the message, specified as MSISDN number in International format with preceding ‘+’ character.

Multiple recipients can be given in a single request. Multiple recipients must be separated by ’; ’.

Maximum number of recipients that can be listed in a single request is 50.
To=+46701234567
To=+46701234567;
+46701234568;
+46701234569
FromNo3Sender of message. If not specified this parameter defaults to client preset name or number.

Maximum of characters accepted depending FromType:
’N’ = 15 characters
’I’ = 15 characters
’S’ = 6 characters
’A’ = 11 characters

Only characters 0-9 and ‘+’ is allow for FromType ‘N’, ‘I’ and ‘S’. Characters 0-9, A-Z, a-z and whitespace are allowed for FromType ‘A’.
From=+46701234567
From=MyCompanyAB
FromTypeNoFormat of the ‘From’-parameter. Defaults to ‘I’=International.

Available formats are ‘N’=National, ‘I‘=International, ‘S’=Short and ‘A‘=Alphanumeric.
FromType=I
FromType=N
FromType=A
FromType=S
MsgYesThe actual message. If message type is binary this parameter should be given in hexadecimal form.Msg=Hello+world
MsgTypeNoMessage type. ‘0’=Text , ‘1’=Flash, ´3´=Binary. Defaults to ‘0’. Additional messages types will be available in later release.MsgType=0
DLRNoDelivery Report requested. ‘0’=NO, ‘1’=YES. Defaults to ‘0’.DLR=1
ExtIdNoExternal Id. To be able to tag each SMS with a reference string of your choice, e.g. a project name. You can then get a monthly report with the number of SMS sent per project. Max 20 characters us-ascii only.ExtdId=MyId
VPNoValidity Period. Number of minutes that message is valid. Defaults to 4320 minutes (3 days). Maximum value is 20160 minutes.VP=1440
FDANoFirst Delivery Attempt. The preferred time when message delivery should first be attempted. The parameter is given in absolute time.FDA=2009-12-01+12%3a00%3a00
TZNoTime Zone. Specifies in which time zone the FDAparameter time is given. Defaults to Europe/Stockholm. See appendix 4.4 for a list of available time zones.TZ=Europe%2FLondon
UDHNoUser Data Header. This parameter is given in hexadecimal form. For advanced users.

Will be prepended to Msg. Message split and concatenation will be handled automatically for nonbinary messages.
UDH=050003FF0201
05 = 5 bytes follow
00 = indicator for concatenated message
03 = three bytes follow
FF= message identification. Each part has the same value
02 = the concatenated message has 2 parts
01 = this is part 1
DCSNoData Coding Scheme. The parameter is used when message type is binary. Acceptable values are 0-255.DCS=0
ERNoEnable reply. ‘0’=NO, ‘1’=YES. Defaults to ‘0’. For future use.ER=1
PrioNoMessage priority, ranging from 0 (lowest) to 3 (highest). Defaults to ‘2’. This parameter is copied to SMPP parameter priority_flag when the SMS is forwarded to the GSM network operator. GSM networks only differ between priority_flag=0 (non-priority) and priority_flag>0 (priority).Prio=1
CharSetNoCharacter set used by the sender of the message (i.e. the character set used by the command shell submitting requests as specified in this API specification). Supported character sets include ISO-8859-1 and UTF-8. This parameter will default to ‘ISO-8859-1’ when not given (as prescribed in HTTP/1.1 RFC 2616, section 3.7.1).CharSet=UTF-8
CodingNoCharacter encoding of the SMS payload when it arrives
on the target handset. Defaults to GSM 7bit character encoding.

The following character encodings are supported:

Coding | max characters/SMS

• ‘0’ = GSM 7bit (default) | 160 characters
• ‘1’ = 8 bit binary (8 bit) | 140 octets
• ’2’ = UCS-2 (16 bit) | 70 characters

See chapter 3.1.5 for an example on how to send a Unicode SMS.
Coding=2
ConcatNoConcatenate ‘0’=NO, ‘1’=YES. Set to ‘1’ if message that results in more than one SMS should be concatenated by the end user terminal. Defaults to ‘1’.Concat=0
MaxMsgsNoMaximum number of concatenated SMS used to carry the message. Defaults to ‘10’ which is also the maximum limit imposed by mobile networks. If the value is set to ‘0’ no length check is performed by SPIRIcom but mobile network limitations are still in place. This parameter should be set to a value in the range 0..10 by users who wants to cap the maximum cost for a single message. This parameter only applies i Concat=’1’.MaxMsgs=3

2.1.3 Response Codes

This is not an exhaustive list of response codes, but the one most likely to be returned.

ResponseDescription
202 Accepted for deliveryMessage has been accepted for delivery.
400 Bad RequestThe request is malformed.
401 UnauthorizedBad credentials.
409 Rate Limit ExceededRate limit exceeded.

In addition to the response code a text description and a unique id is given in the response body, see the examples below.

2.1.4 Delivery Reports

Delivery reports are not sent to the customer per default. To obtain the outcome of a MT-message the user has two options, push or pull. If using push, delivery reports will be sent to the client when available. If using pull, the client will request the status of specific MT-messages at their own discretion.

2.1.4.1 Push

To request that delivery reports be pushed out when a MT-message has reached a final state, set the corresponding parameter in the request (DLR=1).

When requested, delivery reports will be forwarded, as soon as they are received by SMS Gateway. The delivery report is sent using a request to customer. Hostname, port etc. are configurable in the customer portal under Account Settings. Using this information SMS Gateway connects and delivers the report, please see the example section below. The customer must be prepared to accept connections to the given hostname and port.

The report contains two interesting headers regarding the outcome of corresponding SMS. The first is the XResult header. This header contains the actual outcome in written text. If a transaction is successful the header will contain “Delivered”. Please see table below for full reference of possible results. The second header is the X-Transaction-Id. This header contains the same transaction id as was returned in the 202 response received when the message was originally sent. The transaction id can thus be used to map delivery reports to their corresponding SMS.

The request must be responded to by the customer using a 200-response. Please refer to the example section below for an example of how this can be done. The request can be sent over https if requested.

X-ResultDescription
DeliveredMessage has been delivered to the requested destination.
BufferedMessage has been buffered by some entity and is to be delivered.
Delivery failedMessage has not been delivered. Common causes for this problem are phone might be switched of or out of network.

2.1.4.2 Pull

As an alternative to the push method above, the client can pull the status of a MT-message at any time. The DLR-parameter need not be set in the corresponding submit request for the client to use this method.

To do this the client creates and sends a HTTP request containing both login credentials and the transaction id(s) of the MT-message(s). Multiple transaction ids may be given in a single request. If multiple transaction ids are sent, they must be separated by a ‘;’. The URL is constructed using the server hostname and ports given below together with this path:

cgi-bin/getmessagestatus

The table below specifies the parameters for the pull request.

NameMandatoryDescriptionExample
UserYesUsername of client.User=myuser
PassYesPassword of client.Pass=mypassword
TransactionIdYesTransaction id of MT-message.TransactionId=7ac00906-e9ec- 4cbe-a806-ddab2cb4068b
TransactionId=7ac00906-e9ec- 4cbe-a806-ddab2cb4068b; 1ec00906-e9ec-4cbe-a806- dd122cb4068b

SMS Gateway will respond to this request with a 200-response and a body containing the status of the MTmessage.
The result is given in JSON-format . SMS Gateway will respond with a result and a status code for each
transaction id given in the request. The examples below shows the difference between using a single and
multiple transaction ids.

ResultStatusCodeDescription
11The message has been successfully delivered.
21The message could not be delivered.
22The message could not be routed by SPIRIcom.
23The message could not be delivered before the validity period expired.
24Unknown transaction id.
25Internal error.
320The message is pending.

Examples when requesting status using a single transaction id:

{"Result": 1, "StatusCode": 1}
{"Result": 2, "StatusCode": 4}

Examples when requesting status using multiple transaction ids:

{"Results": [{"TransactionId": "0e5d76c2-ca5a-4019-b5e2-08ab66cc101d", "Result": 1, "StatusCode": 1},
{"TransactionId": "eda0ae82-98d7-40b3-bbaa-205b68b63c0b", "Result": 2, "StatusCode": 4}]}
{"Results": [{"TransactionId": "0e5d76c2-ca5a-4019-b5e2-08ab66cc101d", "Result": 1, "StatusCode": 1},
{"TransactionId": "eda0ae82-98d7-40b3-bbaa-205b68b63c0e", "Result": 1, "StatusCode": 1}]}.

2.2 Mobile Originated Messages

2.2.1 Usage

Using SMS Gateway it is possible to receive MO-messages to virtual numbers. To receive MO-messages, the user has two options, push or pull. If using push, MO-messages will be sent to the client when available. If using pull, the client will request the status of specific MO-messages at their own discretion.

When a message has been delivered to the client, either by push or pull, it will be deleted from SMS Gateway. The responsibility for the messsage is thereby handed over to the client.

2.2.2 Push

If configured, SMS Gateway will initiate HTTP requests to the client whenever a new MO-message arrives. Hostname, port, username, password, static parameters etc. are preset in the system when the customer is configured and can be changed later in the web portal. Using this information SMS Gateway connects and delivers the message, please see the example section below. The customer must be prepared to accept connections to the given hostname and port.

The request is much similar in it´s appearance to the MT request message. The request must be responded to by the customer using a 200-response. Please refer to the example section below for an example of how this can be done. The request can be sent over https if requested. It’s recommended that https be used.

2.2.2.2 Parameters

The table below lists available parameters for MO-messages. Parameters not marked as ‘Mandatory’ may be left out of the request by SMS Gateway. Other parameters must be present or the request will be rejected.

All parameters must be URI encoded4: Please refer to the “URI encoding” section 2.5.

NameMandatoryDescriptionExample
ToYesRecipient of the message, specified as MSISDN number in International format with preceding ‘+’ character. Only one recipient can be given in each request.To=+46701234567
FromYesSender of message.From=+46701234567
FromTypeYesFormat of the ‘From’-parameter.

Defaults to ‘I’=International.

Available formats are ‘N’=National, ‘I‘=International, ‘S’=Short and ‘A‘=Alphanumeric.
FromType=I
FromType=N
FromType=A
FromType=S
MsgYesThe actual message.Msg=Hello+world
MsgTypeYesMessage type. ‘0’=Text , ‘1’=Flash. Defaults to ‘0’.

Additional messages types will be available in later release.
MsgType=0
UDHNoUser Data Header. This parameter is given in hexadecimal form. For advanced users.UDH=050003FF0201
DCSNoData Coding Scheme. The parameter is used when message type is binary. Acceptable values are 0-255.DCS=0

2.2.3 Pull

As an alternative to the push method the client can pull waiting MO-messages from SMS Gateway at any time.

To obtain a list of waiting messages construct a GET request to this path:

cgi-bin/getmessagelist

The table below specifies the parameters for the request:

NameMandatoryDescriptionExample
UserYesUsername of client.User=myuser
PassYesPassword of client.Pass=mypassword

The body of the response from SMS Gateway will contain a parameter specifying the number of messages waiting and zero or more transaction ids.

Examples of possible response bodies:

ResponseDescription
{"Result": 1, "Messages": [{"TransactionId": "aa313168-c9f9- 4b25-aa14-38dadfb8ef8e"}, {"TransactionId": "56ef83b9-a535- 46ec-8511-bcb30370f51b"}]}Two messages (with transaction id aa313168-c9f9-4b25-aa14- 38dadfb8ef8e and 56ef83b9-a535-46ec-8511-bcb30370f51b ) are waiting.
{"Result": 1, "Messages": []}No messages are waiting.

A single message can then be retreived using a specific transaction id together with a GET request to this path:

cgi-bin/getmessageforid

The table below specifies the parameters for the request.

NameMandatoryDescriptionExample
UserYesUsername of client.User=myuser
PassYesPassword of client.Pass=mypassword
TransactionIdYesTransaction id of message to be
retrieved.
TransactionId=56ef83b9-a535-46ec-8511-bcb30370f51b

Example of possible response bodies:

ResponseDescription
{"Result": 1, "From": "Test", "FromType": "A", "To": "+4671234567", "ToType": "I", "Msg": "Test", "MsgType": 0, "Timestamp": "2010-09-27 13:02:01"}A message from “Test” to number “+4671234567” containing the message “Test”. Timestamp is given in UTC.
{"Result": 2}The given transaction id is unknown.

The client can also use a single request to directly retreive a message, if there are any available. With this
request the oldest message will be returned.

cgi-bin/getnextmessage

The table below specifies the parameters for the request:

NameMandatoryDescriptionExample
UserYesUsername of client.User=myuser
PassYesPassword of client.Pass=mypassword

Example of possible response bodies:

ResponseDescription
{"Result": 1, "From": "Test", "FromType": "A", "To": "+4671234567", "ToType": "I", "Msg": "Test", "MsgType": 0, "Timestamp": "2010-09-27 13:02:01"}A message from “Test” to number “+4671234567” containing the message “Test”. Timestamp is given in UTC.
{"Result": 3}No more messages are waiting.
{"Result": 4}An internal error occurred.

The following result codes are used in getmessagelist, getmessageforid and getnextmessage.

ResponseDescription
1No error.
2The given transaction id is unknown.
3No more messages are waiting.
4An internal error occurred.

2.2.3.2 Response Codes

ResponseDescription
200 OKThe request has been successfully processed.
400 Bad RequestThe request is malformed.
403 ForbiddenInvalid credentials.
409 Rate Limit ExceededRate limit exceeded.

2.3 Server Hostnames and Ports

This table defines which hostname and port to use for a selected service when submitting the request. Please note that this information may be subject to change and that different information may have been provided along with the username and password.

ServiceHostnamePort
HTTP GETget.spiricom.spirius.com55000
HTTP GET using SSLget.spiricom.spirius.com55001

2.4 Transaction Rate Limit

Clients may be configured with a transaction rate limit to ensure that SMS Gateway will not be overloaded. The limit is calculated as all client initiated requests per seconds, including all requests concerning both MO and MT-messages.

When the rate limit is exceeded requests will be rejected with a “409 Rate Limit Exceeded”-response. Once the client drops below the limit, SMS Gateway will again start processing requests.

2.5 URI Encoding

The Uniform Resource Identifier RFC5 defines which characters are allowed in a URI. Two character sets are defined, reserved and unreserved. Reserved characters are defined as the set of characters that may have a special meaning in a URI. Unreserved characters do not have any special meaning. If a reserved character appears in a parameter this might break the format of the URI. Therefore all parameters must be encoded using percent-encoding before sent. If a character is not in either set (not reserved and not unreserved) it must also be percent-encoded. Refer to RFC3986 for a list of reserved/unreserved characters and how encoding/decoding is done.

3. APPENDIX

3.1 Document History

RevisionDateSignatureComments
01 BETA2010-01-16KJFirst beta version.
1.002010-04-19KJFirst revision 1.00.
1.012010-04-30KJAdding First Delivery Attempt.
1.022010-07-05ESAdded support for binary SMS and more examples.
1.032010-09-13KJAdded support for Virtual Numbers.
1.042010-11-15KJAdded information for URL Encode.
1.052010-12-19KJMinor errors have been corrected.
1.062011-05-03JRChange default MaxMsgs parameter in 2.1.2.
1.072011-05-09JRChange default VP (Validity Period) parameter in 2.1.2.
1.082011-05-23JRAdd Multiple recipients feature.
1.092011-11-08JRAdd a new Result StatusCode in 2.1.4.2.
1.102012-09-12BUAdded info regarding the Coding parameter in 2.1.2.
1.112012-11-01JRServer hostname in 2.4 is change.
1.122014-05-27MKClarification of Charset and Coding in 2.1.2.
1.132014-09-01MKAdd explanation to ExtId in 2.1.2.
1.142015-05-19MKCorrected description of Prio parameter.
1.152015-09-28MKAdded information about maximum limit for parameter ‘To’ and corrected information for parameters ‘MaxMsgs’ and ‘Coding’.
1.162015-10-09MKAdded information UDH in 2.1.2 and Example 3.1.6.
1.172016-05-10MKRemoved incorrect info about basic auth.