Bulk SMS API - SMS to HTTP Web Services

We will pass the inbound SMS text messages sent by your customers to your Two-way SMS Service Number (Virtual Mobile Number or Short Code Number) to your HTTP Web Service.

HTTP(S) POST

Our SMS to HTTP API supports both HTTP and HTTPS and we strongly urge you to use the HTTPS for better security. We do not support HTTP GET because there are security and truncation issues related to passing the message as a query string.

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 build your receiving component to handle unknown tags and do not assume the ordering of the existing tags.

Example HTTP POST request:

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>&Timestamp1=<timestamp>&MessageIdentifier=<messageid>

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 for example 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 HTTP encoding specification.
ReplyTo numeric 15 The telephone number of the mobile phone that sent the message. This will be presented in full international format for example 447700954321
Timestamp1 string 20 The time the message was received. Format: YYYY-MM-DDTHH:MM:SSZ
MessageIdentifier string 8 A unique message identifier (8 hexadecimal digits)
Username
The Username required to access your server as defined by you (see above).
PIN
The PIN required to access your server as defined by you (see above).
SendTo
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 for example 447700912345.
Message
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 HTTP encoding specification.
ReplyTo
The telephone number of the mobile phone that sent the message. This will be presented in full international format for example 447700954321
Timestamp1
The time the message was received. Format: YYYY-MM-DDTHH:MM:SSZ
MessageIdentifier
A unique message identifier (8 hexadecimal digits)

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 Protocol 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.
SmsDeliverPduDataCodingScheme
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
The GSM Protocol 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
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
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.

Two-way SMS Service Configuration

The configuration of your Two-way SMS service (Virtual Mobile Number or Short Code service) is simple and straightforward. Simply login to your account and go to the Two-Way SMS Configuration section in your Account Centre. 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 Fully Qualified Domain Name (FQDN) with an optional port number. For example https://www.example.com:443/incomingmessage.
Username string 20 (Optional) A Username required to access your HTTP server and defined by you. The Username can also be blank in which case you will get an empty tag value. For example Username=&PIN=&... etc.
PIN string 20 (Optional) A 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. For example Username=&PIN=&SendTo=447700912345... etc.
URL
The URL to be used to POST MO message to. It can be HTTP or HTTPS (recommended) and can use an IP address or Fully Qualified Domain Name (FQDN) with an optional port number. For example https://www.csoft.co.uk:443/incomingmessage.
Username
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. For example Username=&PIN=&... etc.
PIN
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. For example Username=&PIN=&SendTo=447700912345... etc.

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

These are the fields that can be present in the HTTP POST response:

Parameter Type Size Description
MessageIdentifier string 8 Optional. The unique identifier given in the POST.
Report numeric 3 Optional. Typically this is 0 unless some error condition has occurred (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.
MessageIdentifier (optional)
The unique identifier given in the POST.
Report (optional)
Typically this is 0 unless some error condition has occurred (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 (optional)
Any descriptive text associated with the response. It is typically used for debugging integration problems.

Your session is about to expire

You will be logged out in seconds.

Do you want to stay signed in?

Yes, keep me signed in     No, Sign me out