Skip to content

Interface description

Introduction

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 HTTP protocol is assumed.

HTTP interface

Mobile terminated messages

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 Gateway can also use SSL-encryption when sending delivery reports back to the client.

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

Name Mandatory Description Examples
User Yes Username of client. User=myuser
Pass Yes Password of client. Pass=mypassword
To Yes Recipient 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
From No1 Sender 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
FromType No Format 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
Msg Yes The actual message. If message type is binary this parameter should be given in hexadecimal form. Msg=Hello+world
MsgType No Message type. 0=Text , 1=Flash, 3=Binary. Defaults to 0. Additional messages types will be available in later release. MsgType=0
DLR No Delivery Report requested. 0=NO, 1=YES. Defaults to 0. DLR=1
ExtId No External 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. ExtId=MyId
VP No Validity Period. Number of minutes that message is valid. Defaults to 4320 minutes (3 days). Maximum value is 20160 minutes. VP=1440
FDA No First 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
TZ No Time 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
UDH No User 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.

For example:
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
 UDH=050003FF0201
DCS No Data Coding Scheme. The parameter is used when message type is binary. Acceptable values are 0-255. DCS=0
ER No Enable reply. 0=NO, 1=YES. Defaults to 0. For future use. ER=1
Prio No Message 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
CharSet No Character 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
Coding No Character encoding of the SMS payload when it arrives on the target handset. Defaults to GSM 7bit character encoding.

The following character encodings are supported:
CodingMax characters/SMS
0 = GSM 7bit (default)160
1 - 8 bit binary (8 bit)140
2 - UCS-2 (16 bit)70
See an example on how to send a Unicode SMS on the examples page.		 Coding=2
Concat No Concatenate 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
MaxMsgs No Maximum 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 if Concat=1. MaxMsgs=3

Response codes

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

Response Description
202 Accepted for delivery Message has been accepted for delivery.
400 Bad request The request is malformed.
401 Unauthorized Bad credentials
409 Rate Limit Exceeded Rate 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.

Delivery reports

Delivery reports are not sent to the customer per default. To obtain the outcome of an 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.

Push

To request that delivery reports be pushed out when an 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-Result Description
Delivered Message has been delivered to the requested destination.
Buffered Message has been buffered by some entity and is to be delivered.
Delivery failed Message has not been delivered. Common causes for this problem are phone might be switched of or out of network.

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 needs 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

Parameters

The table below specifies the parameters for the pull request.

Name Mandatory Description Example
User Yes Username of client. User=myuser
Pass Yes Password of client. Pass=mypassword
TransactionId Yes Transaction ID of MT message. TransactionId=7ac00906-e9ec-4cbe-a806-ddab2cb4068b

TransactionId=7ac00906-e9ec-4cbe-a806-ddab2cb4068b; 1ec00906-e9ec-4cbe-a806-dd122cb4068b
Response codes

SMS Gateway will respond to this request with a 200 response, and a body containing the status of the MT message. 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.

Result StatusCode Description
1 1 The message has been successfully delivered.
2 1 The message could not be delivered.
2 2 The message could not be routed by SPIRIcom.
2 3 The message could not be delivered before the validity period expired.
2 4 Unknown transaction id.
2 5 Internal error.
32 0 The message is pending.

Examples when requesting status using a single transaction id:

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

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

Examples when requesting status using multiple transaction IDs:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "Results": [
    {
      "TransactionId": "0e5d76c2-ca5a-4019-b5e2-08ab66cc101d",
      "Result": 1,
      "StatusCode": 1
    },
    {
      "TransactionId": "eda0ae82-98d7-40b3-bbaa-205b68b63c0b",
      "Result": 2,
      "StatusCode": 4
    }
  ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "Results": [
    {
      "TransactionId": "0e5d76c2-ca5a-4019-b5e2-08ab66cc101d",
      "Result": 1,
      "StatusCode": 1
    },
    {
      "TransactionId": "eda0ae82-98d7-40b3-bbaa-205b68b63c0e",
      "Result": 1,
      "StatusCode": 1
    }
  ]
}.

Mobile originated messages

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 message is thereby handed over to the client.

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 its 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 is recommended that HTTPS be used.

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 encoded. Please refer to the URI encoding section.

Name Mandatory Description Example
To Yes Recipient of the message, specified as MSISDN number in International format with preceding ‘+’ character. Only one recipient can be given in each request. To=+46701234567
From Yes Sender of message. From=+46701234567
FromType Yes Format 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
Msg Yes The actual message. Msg=Hello+world
MsgType Yes Message type. 0 = text , 1 = flash. Defaults to 0.

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

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:

Name Mandatory Description Example
User Yes Username of client. User=myuser
Pass Yes Password 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.

Below are two examples of possible response bodies.

Two messages (with transaction ID aa313168-c9f9-4b25-aa14-38dadfb8ef8e and 56ef83b9-a535-46ec-8511-bcb30370f51b) are waiting:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "Result": 1,
  "Messages": [
    {
      "TransactionId": "aa313168-c9f9- 4b25-aa14-38dadfb8ef8e"
    },
    {
      "TransactionId": "56ef83b9-a535- 46ec-8511-bcb30370f51b"
    }
  ]
}

No messages are waiting:

1
2
3
4
{
  "Result": 1,
  "Messages": []
}

A single message can then be retrieved 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.

Name Mandatory Description Example
User Yes Username of client. User=myuser
Pass Yes Password of client. Pass=mypassword
TransactionId Yes Transaction id of message to be retrieved. TransactionId=56ef83b9-a535-46ec-8511-bcb30370f51b

Below are two examples of possible response bodies.

A message from Test to number +4671234567 containing the message Test. Timestamp is given in UTC:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "Result": 1,
  "From": "Test",
  "FromType": "A",
  "To": "+4671234567",
  "ToType": "I",
  "Msg": "Test",
  "MsgType": 0,
  "Timestamp": "2010-09-27 13:02:01"
}

The given transaction ID is unknown:

1
2
3
{
  "Result": 2
}

The client can also use a single request to directly retrieve 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:

Name Mandatory Description Example
User Yes Username of client. User=myuser
Pass Yes Password of client. Pass=mypassword

Three example of possible response bodies are below.

A message from Test to number +4671234567 containing the message Test. Timestamp is given in UTC:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "Result": 1,
  "From": "Test",
  "FromType": "A",
  "To": "+4671234567",
  "ToType": "I",
  "Msg": "Test",
  "MsgType": 0,
  "Timestamp": "2010-09-27 13:02:01"
}

No more messages are waiting:

1
2
3
{
  "Result": 3
}

An internal error occured: 

1
2
3
{
  "Result": 4
}

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

Response Description
1 No error.
2 The given transaction id is unknown.
3 No more messages are waiting.
4 An internal error occurred.
Response codes
Response Description
200 OK The request has been successfully processed.
400 Bad Request The request is malformed.
403 Forbidden Invalid credentials.
409 Rate Limit Exceeded Rate limit exceeded.

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.

Service Hostname Port
HTTP GET get.spiricom.spirius.com 55000
HTTP GET using TLS get.spiricom.spirius.com 55001

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.

URI encoding

The Uniform Resource Identifier RFC2 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 performed.

  1. Note that a default From-parameter must be configured in the system to be able to leave this parameter out ↩

  2. Uniform Resource Identifiers (URI): Generic Syntax, RFC3986 ↩