Connection Software

 Connection Software

SMS to HTTP(S) POST
Real-time Delivery of Mobile Originated (MO) Messages

With a two-way service your customers can send you SMS text messages. These could be replies to your sent messages or unsolicited messages in response to publishing your two-way number. We can deliver these messages to you in several ways including SMTP (Email), SOAP or HTTP(S) POST. This page describes the SMS to HTTP(S) POST service. It's simple to use and quick to setup or change online.

HTTP(S) POST

We do not support HTTP GET because there are security and truncation issues related to passing the message as a query string. We would strongly urge you to use the HTTPS option rather than simply HTTP for improved security. A Username and PIN can help protect you against any would be spoofing attempt. Thse can simply be your usual account login details if you wish.

A set of tag=value pairs will be passed in the POST command payload for the received message, separated by ampersands (&). It is possible that new tags will be added in the future so you should code your receiving component to handle unknown tags and do not assume the ordering of the existing tags.

POST <your URL> HTTP/1.0
Content-type: application/x-www-form-urlencoded; charset="utf-8"
Content-length: <size of the payload>

Username=<username>&PIN=<pin>&SendTo=<number>&Message=<message>&ReplyTo=<number>

Online Configuration

Configuration is very simple, and usually immediate. Just login to your account and select Configure Services then Two-Way from the menu at the top of the page. You will be prompted to specify the following values:

Parameter Type Size Description

URL

 string 255 The URL to be used to POST MO message to. It can be HTTP or HTTPS (recommended) and can use an IP address or FQDN with an optional port number. For example https://www.csoft.co.uk:443/incomingmessage
Username string 20 Username - the Username required to access your HTTP server and defined by you. The Username can be blank in which case you will get an empty tag value. Username=&PIN=&... etc.
PIN string 20 The PIN required to access your HTTP server and defined by you. The PIN can also be blank in which case you will get an empty tag value. e.g Username=&PIN=&SendTo=447700912345... etc.
Field Descriptions

These are the fields that will be present in the HTTP POST body of a simple text message.

Parameter Type Size Description
Username string 20 The Username required to access your server as defined by you (see above).
PIN string 20 The PIN required to access your server as defined by you (see above).
SendTo numeric 15 The mobile number to which the message was sent. This will be a two-way number/shortcode that you have purchased from Connection Software. For long codes it will be presented in full international format e.g. 447700912345
Message string - The plain text message which was sent to your two-way number/shortcode. It will be in the UTF-8 character encoding with special characters, such as space, encoded using the URL encoding specification.
ReplyTo numeric 15 The telephone number of the mobile phone that sent the message. This will be presented in full international format e.g. 447700954321

If the message is not a simple text message, one or more of the following fields will be present in addition to those listed above. Note that "SmsDeliverPduUserData" replaces "Message" for a binary message.

Parameter Type Size Description
SmsDeliverPduDataCodingScheme hexadecimal string 2 The GSM Data Coding Scheme (TP-DCS), as defined in GSM 03.38. This field is only present if the DCS indicates anything other than a classless text message, or if the PID is present.
SmsDeliverPduProtocolIdentifier hexadecimal string 2 The GSM Protcol Identifier (TP-PID), as defined in GSM 03.40. This field is only present if the PID is non-zero, or if the DCS field is present.
SmsDeliverPduUserDataHeader hexadecimal string - The GSM User Data Header (UDH), as defined in GSM 03.40. This field is only present if the TP-UDHI flag was set in the message.
SmsDeliverPduUserData hexadecimal string - The GSM User Data (TP-UD), excluding the UDH (if any). This field replaces the "Message" field for 8-bit data.
Originating Domains

The domains where the HTTP POST request could be originated from are
s3.itsarrived.net
s4.itsarrived.net
We use load balancing techniques so you should not assume that messages with ever come from one or the other. You may need to use these when configuring your firewall.

HTTP Response

You must respond to each HTTP POST in order for the server to know that the message was received and processed properly. If you do not, the same message may well be sent repeatedly with others being queued behind it.

The response must be an "HTTP 200 OK".

We recommend a message body as as shown below, as this aids debugging, but we assume success with just the 200 OK response. The format is similar the POST format (i.e. tag=value). For example:

HTTP/1.1 200 OK
Date: Wed, 03 Jul 2002 09:31:42 GMT
Server: Apache/1.3.22 (Unix) (Red-Hat/Linux) mod_ssl/2.8.5
OpenSSL/0.9.6b DAV/1.0.2 PHP/4.0.6 mod_perl/1.24_01 mod_fastcgi/2.2.10
Content-Type: text/html; charset=utf-8
Content-Length: 45

MessageIdentifier=3C7D98A4&Report=0&Text=OK

Field Descriptions

The fields in the response are as follows

Parameter Type Size Description

MessageIdentifier

 string 15 Optional. The unique identifier that matches up to the one that was returned to you when the message was originally submitted.
Report numeric 3 Optional. Typically this is 0 unless some error condition has occured (such as an invalid Username or PIN) in which case you can either return the correct report code or default to the "catch all" of -1. The report code must match the Connection Software specified numbers, however; do not use your own.
Text string 255 Optional. Any descriptive text associated with the response. It is typically used for debugging integration problems.

SMS This page was last modified at 15:36 UTC on Thursday June 17, 2010