Interface description

Introduction

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 HTTP protocol and the command line tool curl is assumed.

HTTP interface

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:

You send the question What time are you coming? to mobile user +46123456789.
You get transaction-id {1} in return from the Smart Replypath API.
You send another question What time does the game start? to the same mobile user.
You get transaction-id {2} in return from the Smart Replypath API.
The mobile user replies to one of the questions with the text At 10:30.
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.

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 Replypath API will not accept any requests until they have been accepted by the underlying HTTPS GET Interface.

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

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

REST-ful example

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

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

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" }'

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 HTTP error codes for details.

HTTP error codes

Code	Response	Description
`200`	OK	Request was received and processed.
`400`	Bad Request	Invalid parameter, more details are given in the error description.
`401`	Unauthorized	Wrong 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.
`411`	Length Required	POST request with missing body and/or missing Content-Length header.
`500`	Application Error	Please report to support@spirius.com
`503`	Service Unavailable	The 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"}

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 more than five minutes since last SMS was sent has elapsed (because of caching).

HTTP GET

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

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"
}

E-mail

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