Sending SMS Text Messages Web Service SOAP API
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 sending SMS
messages to mobile/cell phones around the world. The WSDL is
available below and enables rapid integration using
modern SOAP development toolkits like gSOAP and .NET.
Web Service Definition Language (WSDL)
The WSDL files are available for our primary server at
http://www.csoft.co.uk/dtd/www.sendsms5.wsdl
and our secondary server at
http://www2.csoft.co.uk/dtd/www2.sendsms5.wsdl
Element Descriptions
Use the SubmitMessage call for sending SMS messages as described below. You may also find the
Available Credit and Available Messages calls of
use. There may be other calls defined within the WSDL but these are not relevant when sending SMS.
We recommend that you only try to send one type of message in each SOAP request, but you can send that message
to multiple receipients using the Recipient section. All the element names are case sensitive
so "Data" is correct but "data" will
not work. To aid readability a plus (+) prefix indicates a complex type, while the indenting and
dash (-) prefix indicates an element in the sequence of elements that form part of that complex type. The + and - are not
part of the element names, however.
| Element Name |
Required |
Description |
| + SubmitMessage |
Required |
Operation request element |
| - Username |
Required |
An alphanumeric string with a maximum size of
20 characters e.g. ANOther.61234. This is sent to you when
you sign-up for
the service. |
| - PIN |
Required |
An alphanumeric string with a maximum size of 20
characters e.g. 123456. This is sent to you when
you sign-up for
the service. |
| + Recipient |
Required |
This is a wrapper for all the information about
the recipient. |
| - SendTo |
Typically required |
The number of the mobile phone to which the message
should be sent. The number should be in full International
Format, including the Country Code. For example 447700912345
for a UK mobile
The message can be sent to multiple recipients
by separating each number with a comma e.g. 447700912345,
23412345678, 19145551234, 447700912346.
We suggest that you do not put more than 350 numbers
in each request but you can submit
as many requests as you need, in series or in parallel.
|
| - SendToAddressBook |
Optional |
You can specify the name of your Address Book to use as
the list of numbers to send your content to. To specify a group within that Address Book, suffix the
address book name with a double colon and the group name. e.g. SendToAddressBook=MyAddressBook::Friends
|
| + SendOptions |
Optional |
These affect the way a message is delivered.
|
| - SendTimeAbsolute |
Optional |
Specifies the exact date and time that you want the message to be sent. This must be in UTC (GMT) and is a maximum of seven
days into the future.
|
| - SendTimeDelay |
Optional |
Specifies the number of minutes that the message should be delayed. The value must be between 1 minute and 10080 minutes
(seven days).
|
| - DeliveryOption |
Optional |
Specifies the type of delivery service
you wish to use to deliver the message. The permitted
values are of the enumerated type ns2:DeliveryOption ‘Default’, ‘Premier’, or ‘Economy’.
When not specified, an unrecognized value is passed,
or ‘Default’ is selected, the setting
on the website account is used.
|
| + Message |
Required |
The Message element is essentially just a wrapper and you will need to define the type of message (TextMessage or FlashMessage). |
| - TextMessage |
Either |
The message is a plain text message. Remember
than <CR> and <LF> characters are counted
if sent. |
| - FlashMessage |
Either |
The message between the elements is sent as a flash
message and is displayed immediately it is received
on the phone. There is no need to press "read" |
- ReplyTo |
Optional |
If your account has been set up to change the ReplyTo
shown with the message, then you can set it here. See two-way for
details of how you can change this. Invalid entries here will be ignored. |
| - MessageIdentifier |
Reserved |
This section is reserved for use by Connection Software and
should be omitted or null. |
| - Reserved |
Reserved |
This section is reserved for use by Connection Software and
should be omitted or null. |
Responses will contain the following elements.
| Element Name |
Required |
Description |
| + SubmitMessageResponse |
Required |
Operation response element |
| - MessageIdentifier |
Required |
A unique alphanumeric string of up to 31 characters that can be used to
track each message in the server logs and in the real-time delivery receipts (if enabled).
If you submit multiple numbers in the SendTo tag, this will be a comma separated list of id's in the same
order as the submitted numbers. |
| - Report |
Required |
A numeric report code. If you submit multiple numbers in the
SendTo tag, this will be a comma separated list of codes in the same order as the submitted numbers. |
| - Text |
Optional |
A description of the Report designed to provide more information to help in debugging. This may be
blank. If you submit multiple numbers in the SendTo tag, this will be a comma separated list of
descriptions in the same order as the submitted numbers. |
| - Reserved |
Reserved |
This whole section is reserved for use by Connection Software and
should be ignored when parsing responses. |
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).
Character Encoding
We fully support sending messages in international character
sets (such as Chinese, Hebrew, Russian, etc) using the Unicode encoding standard UTF-8. Typically, SOAP toolkits use the UTF-8 character set by default, so it is unlikely that you need to do anything special in order to send
messages in almost any language. If you do experience problems, such as garbled messages, then ensure the handset can display such messages and that
the character set in the HTTP POST header and the xml encoding tag are both set to UTF-8 (see the examples below).
Compatibility
The current interface has been validated in-house against gSOAP and Microsoft VB/VC++/VC# .NET for compatibility but many of our clients have reported it working equally well with other languages that support developing SOAP clients.
Sample applications for sending SMS using Microsoft Visual C#, C++ and Visual Basic .NET are available in the sample code section.
.NET
To use the service from a Visual Studio .NET application you need to build a proxy class from our web service definition file (WSDL). Open the project you want add SMS functionality to -
this can be an ASP.NET page or a stand-alone Windows form-based application. Right-click on the References folder in the Solution Explorer and choose "Add Web Reference.".
Type in the Connection Software Send SMS Web Service WSDL (http://www.csoft.co.uk/dtd/sendsms5.wsdl) and press enter. This will download the Web service definition from our server.
To create a proxy class for this Web service, simply click the Add Reference button. Then simply instantiate the class and call the method SubmitMessage with the values described above to begin sending SMS.
Unable to generate a temporary class (result=1). error CS0030: Cannot convert type 'csoft.item[]' to 'csoft.item'
If you experience this known .NET issue you need to edit the auto-generated CSoftSmsService.cs file and change public item[][] info to public item[] info.
See either the C# Sample Code for an example solution and the Microsoft issue that relates to this
problem. Note that while the issue refers to Biz Talk it is a known issue with .NET also.
Case Sensitivity
All element names in SOAP are case sensitive. It has been reported that some toolkits do not honour this.
Authentication, Security and Fail-over
The SOAP API will authenticate you using your account Username and PIN (not Password). These will have been sent to you when you signed up.
We support both SOAP over HTTP and HTTPS but we strongly recommend HTTPS for greater security of your account information.
We have two public SOAP services, as shown below. We strongly
urge you to implement fail-over to the secondary service in the event that the primary service is unavailable. Should we ever need to take down a service, we will always seek to ensure that the other is still
running.
Primary
Service
Address |
https://www.csoft.co.uk/sendsms5
http://www.csoft.co.uk/sendsms5
|
Secondary
Service
Address |
https://www2.csoft.co.uk/sendsms5
http://www2.csoft.co.uk/sendsms5
|
| Username |
Is automatically supplied when you sign-up for
the service. |
| PIN |
Is automatically supplied when you sign-up for
the service. |
Example SOAP Requests
These examples have been formatted for display purposes
and so may contain invalid whitespace.
Plain Text Message
To send a plain text message you will need to include at least the Username, PIN, Recipient,
and TextMessage elements in your SOAP packet. Remember that SOAP uses the UFT-8 encoding by default so
all message text must be encoded as UTF-8. This is especially important for international character sets.
<?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:SubmitMessage>
<Username xsi:type="xsd:string">Another.12345</Username>
<PIN xsi:type="xsd:string">123456</PIN>
<Recipient xsi:type="ns2:Recipient">
<SendTo xsi:type="xsd:string">447700912345,447700911223</SendTo>
<SendOptions xsi:type="ns2:SendOptions">
<DeliveryOption xsi:type="ns2:DeliveryOption">Economy</DeliveryOption>
</SendOptions>
</Recipient>
<Message xsi:type="ns2:Message">
<TextMessage xsi:type="xsd:string">test message</TextMessage>
</Message>
</ns2:SubmitMessage>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Example SOAP Responses
Success response
HTTP/1.1 200 OK
Date: Wed, 18 Jun 2003 09:06:54 GMT
Server: Apache/1.3.23 (Unix) (Red-Hat/Linux) mod_ssl/2.8.12
OpenSSL/0.9.6b DAV/1.0.3 PHP/4.1.2 mod_perl/1.26 mod_fastcgi/2.2.12
Content-Length: 899
Connection: close
Content-Type: text/xml; charset=utf-8
<?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:ns1="http://www.csoft.co.uk/dtd/sendsms2.xsd"
xmlns:ns2="http://www.csoft.co.uk/dtd/sendsms5.xsd">
<SOAP-ENV:Body SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<ns2:SubmitMessageResponse xsi:type="ns2:SubmitMessageResponse">
<MessageIdentifier xsi:type="xsd:string">302B461B,302B461C</MessageIdentifier>
<Report xsi:type="xsd:int">99,99</Report>
<Text xsi:type="xsd:string">Test message succeeded,Test message succeeded</Text>
<Reserved xsi:type="ns2:Reserved">
<Field1 xsi:type="xsd:string"></Field1>
</Reserved></ns2:SubmitMessageResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
The report code -2 indicates that the message has
been received by It's Arrived for processing. See Report
Codes.
Failure response
HTTP/1.1 200 OK
Date: Wed, 18 Jun 2003 09:12:15 GMT
Server: Apache/1.3.23 (Unix) (Red-Hat/Linux) mod_ssl/2.8.12
OpenSSL/0.9.6b DAV/1.0.3 PHP/4.1.2 mod_perl/1.26 mod_fastcgi/2.2.12
Content-Length: 855
Connection: close
Content-Type: text/xml; charset=utf-8
<?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:ns1="http://www.csoft.co.uk/dtd/sendsms2.xsd"
xmlns:ns2="http://www.csoft.co.uk/dtd/sendsms5.xsd">
<SOAP-ENV:Body SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<ns2:SubmitMessageResponse xsi:type="ns2:SubmitMessageResponse">
<MessageIdentifier xsi:type="xsd:string">302B4645,302B4646</MessageIdentifier>
<Report xsi:type="xsd:int">2,2</Report>
<Text xsi:type="xsd:string">For more detailed
information on this Report number, please visit www.csoft.co.uk</Text>
<Reserved xsi:type="ns2:Reserved"></Reserved>
</ns2:SubmitMessageResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
The report code 2 indicates an invalid login. See Report
Codes
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.
|
