SMS Gateway
Interface Description
Smart Replypath v1.0

Document nameSmart Replypath v1.0
Document numberEMK16002SSR
Revision1.0
AuthorMartin Kristell
Date2016-09-21
Information classOpen Information
ReviewerJonas Rexeke
Review date2016-09-21
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 document describes Spirius Smart Replypath Interface. It gives the basics of how to use the API and provides a short description of available parameters.

The document is intended for application developers and/or integrators. Basic knowledge of the HTTP1 protocol and the command line tool curl2 is assumed.

2. HTTP Interface

2.1 Introduction

The idea with Smart Replypath is to be able to send several questions via SMS to the same mobile user and to be able to map the responses to the questions.

Use case example:

  1. → You send the question “What time are you coming?” to mobile user +46123456789.
  2. ← You get transaction-id {1} in return from the Smart Replypath API.
  3. → You send another question “What time does the game start?” to the same mobile user.
  4. ← You get transaction-id {2} in return from the Smart Replypath API.
  5. The mobile user replies to one of the questions with the text “At 10:30”.
  6. ← You get the message “At 10:30” received in response to {1} from the Smart Replypath application.

This functionality is achieved by using a unique phone number as sender for each question. When the user responds to a question, the reply can be mapped to the question using the unique phone number.

The mapping for the unique numbers will be kept for a limited time only, this time is called the Validity Period (VP). The default VP value is three days. Any response coming in after the VP has expired will not be forwarded.

Because Smart Replypath require functionality provided by Extended Virtual Numbers, it will only work within Sweden which is the only country where the mobile phone networks are configured to allow extension digits to be added to a mobile phone number.

2.1.1 Access points

Smart replypath is implemented as a layer in front of Spirius HTTPS GET Interface for sending and receiving SMS from Internet applications. It is able to make use of all Spirius’s HTTPS GET Interface access points, but the smart replypath application itself does not provide geographic redundancy and is only available from a single location:

https://smartreplypath.spirius.com:55001

The Smart Replpath API will not accept any requests until they have been accepted by the underlying HTTPS GET Interface.

2.1.2 Request syntax

The requests are secured by HTTPS and authenticated using Basic Authentication as defined in RFC 2617 (Credentials are encoded in the Authorization request-header field).

The API provides support for three kinds of HTTP requests. Traditional GET, REST-ful GET and POST with json body. The REST-ful style doesn’t allow you to specify all parameters and is mainly intended to facilitate demonstration and testing using a web-browser.

The message text must be encoded in UTF-8. GET requests must have URL-encoded parameters and the POST request a json-encoded body.

Traditional GET example:

curl -i -X'GET'
"https://srp.spirius.com:55001/v1/replypath/sendsms?To=%2B461234&Msg=abc" -u User:Pass

Restful example:

curl -i -X'GET'
"https://srp.spirius.com:55001/v1/replypath/sendsms/%2B461234/abc" -u User:Pass

POST example:

curl -i -X'POST' "https://srp.spirius.com:55001/v1/replypath/sendsms"
-u User:Pass
-H 'Content-Type: application/json'
-d '{ "To":"+46123456789", "Msg":"abc" }'

If you enter a request from a web-browser you will be promted for credentials by a popup dialog.

2.1.3 Response syntax

The reponse will be json-encoded, API-friendly and intended for computers rather than humans.

Sample response for the simple request given in the Request syntax section above:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 121
Date: Fri, 09 Sep 2016 09:16:19 GMT
Server: 0.0.0.0
[
    {
        "DestinationAddress": "+461234",
        "TransactionId": "982ab383-9d50-4c73-a064-776a04b559ca"
    }
]

Should there be anything wrong with the request, it will be rejected with an HTTP Error Code indicating the nature of the problem, please see section 2.1.4 for details.

2.1.4 HTTP Error Codes

CodeResponseDescription
200OKRequest was received and processed
400Bad RequestInvalid parameter, more details are given in the error description.
401UnauthorizedWrong user or password. It could also be one of following reasons:
• User lack access rights for the Smart Replypath service.
• Account is inactive because the contract has been terminated.
• Account is on prepaid agreement and has run out of funds.
• Account has IP restriction enabled and the request is coming from an IPv4 address not in the whitelist.
The underlying HTTPS GET API can be queried directly to better understand the reason in case the Smart Replypath application returns a 401 error code.
411Length RequiredPOST request with missing body and/or missing Content-Length header.
500Application ErrorPlease report to support@spirius.com
503Service UnavailableThe server is currently unable to handle the request due to a temporary overloading or maintenance of the server.

Also responses indicating an error have json-encoded bodies.

curl -i -X'GET' "https://srp.spirius.com:55001/v1/replypath/sendsms/abc/12"
-uUser:Pass
HTTP/1.1 400 Bad Request
Date: Fri, 09 Sep 2016 09:35:50 GMT
Content-Length: 513
Content-Type: application/json
Allow: GET, HEAD, POST
Server: CherryPy/8.1.0

{"status": "400 Bad Request", "message": "Invalid to number: abc"}

2.1.5 Request Parameters

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

NameMandatoryDescriptionExample
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 10.
In HTTP GET requests the ‘+’ character should be URL-encoded, i.e. given as %2B.
To=+4670123456789

To=+4670123456789; +46701234568; +46701234569
MsgYesMessage text encoded in UTF-8.
The Maximum number of characters that will be accepted by the Smart Replypath API in a single message is 1530 (although it is not guaranteed that the message will fit into the maximum 10 concatenated SMS that is possible since some characters require more space in GSM-7 encoding).
DLRNoDelivery Report requested. ‘0’=NO, ‘1’=YES.
Defaults to ‘0’.
DLR=1
VPNoValidity Period. Number of minutes that question is valid and can be responded to. The time is calculated from when the message is accepted by the Smart Replypath API (i.e. not from the time the message is received on the handset)
Defaults to 4320 minutes (3 days).
Maximum value is 10080 minutes (7 days).
VP=1440
OneShotNoIf this parameter is set to 1, only a single (the first) response will be forwarded by the Smart Replypath application.
Defaults to ‘0’.
OneShot=1

2.1.6 Response Body Parameters

The parameters that can be given in the response body are listed in the table below.

NameMandatoryDescriptionExample
DestinationAddressYes
TransactionIdNoOnly present if the message was accepted by the backend. The TransactionId is created by the backend (i.e. it is not local to the Smart Replypath application).
ErrorCodeNoHTTP Status Code from the backend in case the message was not accepted. Please refer to SPIRIcom HTTP GET Interface description for further details.
ErrorDescriptionNoError description given by the backend in case the message was not accepted. Please refer to SPIRIcom HTTP GET Interface description for further details.

3. USER RESPONSES

The replypath URL configured for the account shown in the first two the examples below is: http://localhost:80/reply. This URL is transferred from Spirius’s backend to the Smart Replypath application every time your account is re-authorised. That means that after changing this URL, the change is not in effect until you send a new SMS via the replypath server and only if it is more than five minutes since last SMS was sent (because of caching).

3.1.1 HTTP GET

127.0.0.1 - - [15/Sep/2016 20:31:45] "GET /reply?Msg=Ja+tack&InResponseTo=2531e755-71d0-4449-bb0c-e5657d13c570

3.1.2 HTTP POST

127.0.0.1 - - [15/Sep/2016 20:59:10] "POST /reply HTTP/1.1" 200 -
{
    "From": "+4612345",
    "InResponseTo": "21d318ca-6598-4e3a-9212-f6b8ab5e79ae",
    "Msg": "Ja tack"
}

3.1.3 E-mail

The E-mail delivery is mainly for testing purposes. Beware that a large number of emails might trigger SPAM filters.

4. APPENDIX

4.1 Document history

RevisionDateSignatureComments
0.012016-09-09MKFirst draft
1.002016-09-21MKV1.0 Released