Connection Software

 Connection Software

Receiving SMS Text Messages Web Service SOAP API
With a two-way service your customers can send mobile originated (MO) SMS text messages to an assigned two-way telephone number, or short code, and the messages will then be immediately forwarded to you using SOAP over HTTP(S).

SOAP is an XML-based protocol for the exchange of information in a decentralized, distributed environment. Because of SOAP's flexibility and extensibility it is well suited to the rapidly developing messaging market.

We offer an extensive and flexible SOAP API for receiving SMS. The WSDL and XSD are available below and enable rapid integration using modern SOAP development toolkits like gSOAP and .NET.

Web Service Definition Language and Schema

The WSDL and XSD files are available at
http://www.csoft.co.uk/dtd/sendsms5.wsdl
http://www.csoft.co.uk/dtd/sendsms5.xsd
with backup at
http://www2.csoft.co.uk/dtd/sendsms5.wsdl
http://www2.csoft.co.uk/dtd/sendsms5.xsd

The WSDL file is the definitive resource for determining the API specification.

Configuration

We need to know the following details before we can deliver the MO messages to you. You can configure this yourself on the website as part of the two-way set-up when chosing SOAP as the delivery method.

Parameter Type Size Description

Server Address

 string 80 The server address (IP or FQDN) that you wish us to connect to. e.g https://www.mycompany.com
Port Number number 0 to 32000 Optional. The port number to connect to on your server. This is usually port 80 for SOAP over HTTP and will be defaulted as appropriate if left out.
URI string 255 The URI to be used by the POST command - for example /cgi-bin/delivermessage.pl
Username string 20 A Username required to access your server implementation of this API. This is defined by you and is optional.
PIN string 20 A PIN required to access your server implementation of this API. This is defined by you and is optional.
SOAP Request Elements
Parameter Type Size Description
Username string 20 A Username required to access your server implementation of this API. This will be a nil element if you do not define it.
PIN string 20 A PIN required to access your server implementation of this API. This will be a nil element if you do not define it.

SendTo

 numeric 15 The phone number of the device which received the message, normally in E.164/2000 format e.g. 447700912345
ReplyTo string 40 The phone number or text shown as the originator of the message. This will usually be an E.164/2000 format telephone number e.g. 41327654321 which has a maximum of 15 digits. Alternatively it could be a text string of up to 11 characters. However in the future this may be used to hold longer strings and you should allow for up to 40 characters.
TextMessage string 480 The SMS message. Special characters will be encoded according to the SOAP specification. The SMS message can only contain 160 characters at present but when utf-8 encoded this could generate 3x160=480 characters.

Any other elements that may be included can safely be ignored.

SOAP Response Elements
Parameter Type Size Description
Report numeric 3 Required. To indicate successful acceptance of the SOAP packet this should be 0. The report number must match the Connection Software specified numbers.

MessageIdentifier

 numeric 15 Usually a nil element, this can be your own unique identifier for the message.
Text string 255 Usually a nil element, this can be any descriptive text associated with the response.
Example SOAP Request
POST /cgi-bin/delivermessage.pl HTTP/1.0
Host: www.somecompany.com
Content-type: text/soap; charset="utf-8"
Content-length: 978

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope 
xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" 
xmlns:xsd="http://www.w3.org/1999/XMLSchema" 
xmlns:ns2="http://www.csoft.co.uk/dtd/sendsms5.xsd">
	<SOAP-ENV:Body>
		<DeliverMessage xmlns="http://www.csoft.co.uk/dtd/sendsms5.xsd">
			<Username xsi:type="xsd:string">ANother.123456</Username>
			<PIN xsi:type="xsd:string">12345678</PIN>
			<Recipient xsi:type="ns2:Recipient">
				<SendTo xsi:type="xsd:string">447700912345</SendTo>
			</Recipient>
			<Message xsi:type="ns2:Message">
				<TextMessage xsi:type="xsd:string">another text message</TextMessage>
			</Message>
			<ReplyTo xsi:type="xsd:string">447624806286</ReplyTo>
		</DeliverMessage>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example SOAP Response
HTTP/1.0 200 OK
Content-type: text/soap; charset="utf-8"
Content-length: 681

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
 xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:ns2="http://www.csoft.co.uk/dtd/sendsms5.xsd">
	<SOAP-ENV:Body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
		<ns2:DeliverMessageResponse>
			<Report xsi:type="xsd:int">0</Report>
			<MessageIdentifier xsi:type="xsd:string">3C7D98A4</MessageIdentifier>
			<Text xsi:type="xsd:string"></Text>
		</ns2:DeliverMessageResponse>
	</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
SMS This page was last modified at 9:45 UTC on Tuesday August 21, 2007