Sending SMS Text Messages Web Service
HTTP API

You can use the SMS Messaging Web Service HTTP API to send one, or hundreds, of text messages in seconds. The interface is simple to integrate with, particularly from websites and scripting languages such as Perl, Javascript and PHP and quick to setup. We provide free sample code in some of the most common to get you started.

HTTP Request

The HTTP POST request body comprises a set of tag=value pairs separated by ampersands (&) that specify the content that you want to send. For example, to send the message "Hello World" you would send a request like this:

POST /webservices/http/sendsms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Connection:close
Content-Length: 75

Username=ANOther.12345&PIN=123456&SendTo=447700912345&Message=Hello%20World

Servers, Security & Failover

We have multiple servers, two of which are available for public use with this API, so that in the event of an failure you should still be able to connect to us. At least one of these servers should always be available and for maximum reliability we stronly urge you to write your application to failover to the secondary server should the primary not be available for any reason.

We support both HTTP and HTTPS protocols but we strongly urge you to use HTTPS for greater security of your account information. You may use a GET rather than a POST but GET suffers from truncation limitations and has greater security issues, since you can very easily see the entire message including your Username and PIN on the URI line.

The HTTP API will authenticate you using your account Username and PIN (not Password). These will have been sent to you when you signed up.

Primary Server
https://www.csoft.co.uk/webservices/http/sendsms
http://www.csoft.co.uk/webservices/http/sendsms

Secondary Server
https://www2.csoft.co.uk/webservices/http/sendsms
http://www2.csoft.co.uk/webservices/http/sendsms

Header Fields

When using the POST command you must specify the correct HTTP headers. In particular, the following must be set;

Host: www.csoft.co.uk
Content-Length: <the length of the query string>
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Connection:close

Character Encoding

See Encoding Characters for information about how to URL encode plain text messages that contain special characters (such as space, ampersand, and quote). There is also a useful reference at W3Schools on the subject.

If you wish to send messages in international character sets (such as Chinese, Hebrew, Russian, etc) use the Unicode UTF-8 encoding standard. When sending messages using the UTF-8 character set, be sure that the receiving phone device can accept and display messages in that language and note that the maximum size of a single message is then reduced to 70 utf-8 characters.

Each octet of the UTF-8 character you are encoding must be encoded as a separate hex encoded character. For example, to send the Hebrew Alef (Unicode 5D0) character you would use the following HTTP POST:

POST /webservices/http/sendsms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Connection:close
Content-Length: 68

Username=ANOther.12345&PIN=123456&Message=%D7%90&SendTo=447700912345

Parameter Description

HTTP Response

The Server will only respond back once the whole SendTo list has been processed. If the message is successfully sent to everyone on the SendTo list then the Server will respond with a success message, or messages. If any of the numbers fail, it will continue to process the list, but the response will depend on the optional ResponseFormat chosen in the HTTP request. The default is format 0.

When ResponseFormat=0 the response is:

<report number><space><hyphen><space><report message>

For example

HTTP/1.1 200 OK
Date: Tue, 10 Dec 2002 14:33:38 GMT
Server: Apache/1.3.23 (Unix) (Red-Hat/Linux) mod_ssl/2.8.7
OpenSSL/0.9.6b DAV/1.0.3 PHP/4.1.2 mod_perl/1.26 mod_fastcgi/2.2.12
Transfer-Encoding: chunked
Connection:close
Content-Type: text/html;

171 - Invalid login

When ResponseFormat=1 the response format is a tag=value style that is more appropriate for parsing. It uses the new report codes and the associated unique Message Identifier but will only return a single value for each tag, irrespective of how many numbers were submitted at once. If a failure occurs, the response will be the last failure. If all the messages succeed, the response will be for the last number.

HTTP/1.1 200 OK
Date: Tue, 10 Dec 2002 14:33:38 GMT
Server: Apache/1.3.23 (Unix) (Red-Hat/Linux) mod_ssl/2.8.7
OpenSSL/0.9.6b DAV/1.0.3 PHP/4.1.2 mod_perl/1.26 mod_fastcgi/2.2.12
Transfer-Encoding: chunked
Content-Type: text/html;

MessageIdentifier=30106CCE&Report=2&Text=Invalid%20Login

When ResponseFormat=3 the response format is a tag=value style that is more appropriate for parsing. It uses the new report codes and the associated unique Message Identifier and will return a value for each tag for each number submitted, with multiple values separated by a comma.

HTTP/1.1 200 OK
Date: Tue, 10 Dec 2002 14:33:38 GMT
Server: Apache/1.3.23 (Unix) (Red-Hat/Linux) mod_ssl/2.8.7
OpenSSL/0.9.6b DAV/1.0.3 PHP/4.1.2 mod_perl/1.26 mod_fastcgi/2.2.12
Transfer-Encoding: chunked
Content-Type: text/html;

MessageIdentifier=30106CCE,30106CCF&Report=%2D2,15&Text=Accepted%20by%20csoft%3A%20queued,Out%20of%20credit

The fields in the response are as follows

Handling Report Codes

There are alot of different report codes listed, and you do not need to handle them all since many of them are never returned by API's. The full list is available from the report code pages, but for this API, the codes that you should definitely handle for a good client implementation are as follows:

-3, -2, -1, 0, 2, 3, 5, 6, 7, 8, 11, 12, 13, 14, 15, 20, 76, 98, 99

Efficiency Considerations

If you plan to send multiple messages then, using HTTP 1.1, you may remove the Connection:close header and take advantage of a Keep-Alive connection. Note that the server will timeout and terminate your connection, however, if you do not send each message in quick succession. Furthermore, if you are sending the same message to multiple recipients do not send each as a seperate HTTP POST. It is more efficient (and very much faster) to include each number as a comma seperated list in the same packet (see below).

Examples

You can download free sample code in some of the most common programming languages to get you started and there are some content based examples below. Note that where an example is broken across more than one line, this is for readability and must not be submitted that way.

Sending a plain text SMS message

POST /webservices/http/sendsms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Connection:close
Content-Length: 76

UserName=ANother.12345&PIN=123456&SendTo=447700912345,447700911223&Message=Connection%20Software&
ResponseFormat=1&DeliveryServiceOption=Economy

Sending a flash SMS message

Flash messages appear on the screen of the mobile without the user having to select "read message". Flash messages are suitable for fast changing information that needs to visible immediately.

POST /webservices/http/sendsms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Connection:close
Content-Length: 81

Username=ANOther.12345&PIN=123456&SendTo=447700912345&FlashMessage=Golf%20Course

Dealing with Errors

• If you are unable to establish a TCP/IP connection with www.csoft.co.uk then it is vital that you automatically failover to www2.csoft.co.uk.
• If you receive a response code indicating an error condition DO NOT automatically retry your request. For example if you are Out of Credit you will still be Out Credit. If you do enter a retry loop we may block your IP address as repeated retries may appear to us to be a Denial of Service attack.

Format One (deprecated)

This format is somewhat deprecated as it can only be used to send plain text messages. You should NOT use this if you plan to send other content such as ringtones, wallpapers or java games or to use advanced features such as delayed delivery. Use the newer, richer, format above if you think you will want to send content other than plain messages at any point.

The format of the HTTP request

The HTTP request includes a set of parameters that specify the message you want to send. With Format 1 you can only send plain text messages. For example to send the message "Is 50% OK?"

POST /webservices/http/sendsms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Connection:close
Content-Length: 64

UN=ANOther.12345&PIN=123456&N=447700912345&M=Is%2050%25%20OK%3f

Parameter Description

The format of the HTTP(S) response

The Server will only respond back once the whole recipient list has been processed. If the message is successfully sent to everyone on the list list then the Server will respond with 01. If any of the numbers fail, it will continue to process the list, but the Server will respond with a failure for the last number that failed irrespective of how many numbers actually failed.

The format of the response is as follows;

HTTP/1.1 200 OK
Date: Tue, 10 Dec 2002 14:33:38 GMT
Server: Apache/1.3.23 (Unix) (Red-Hat/Linux) mod_ssl/2.8.7 OpenSSL/0.9.6b DAV/1.0.3 PHP/4.1.2 mod_perl/1.26 mod_fastcgi/2.2.12
Transfer-Encoding: chunked
Content-Type: text/html;

99

Response codes

The possible response codes are as shown in the table below. Note that because this interface is designed to be compatible with some other operators, the codes are not consistent with the more extensive 'report codes' used by Connection Software in the other interfaces.

Dealing with Errors

• If you are unable to establish a TCP/IP connection with www.csoft.co.uk then it is vital that you automatically failover to www2.csoft.co.uk.
• If you receive a response code indicating an error condition DO NOT automatically retry your request. For example if you are Out of Credit you will still be Out Credit. If you do enter a retry loop we may block your IP address as repeated retries may appear to us to be a Denial of Service attack.