Connection Software

Sending Multimedia Content 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 multimedia messages to mobile/cell phones around the world. The WSDL available below 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

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
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.

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).

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.

Choosing The Right Message Type

When you look at the element descriptions below you will see there are a large number of different types of Message possible. For example, You can deliver many types of multimedia content using either WAP PUSH or MMS Notification. These are two different methods and they communicate with quite different components on the user's phone. Some phones have only WAP capability, others have an MMS capability too. Most modern phones support both, so the decision on which to use usually depends on the type of content you are sending. This provides great flexibility, but can be confusing. Here's how to decide what to use for your content.

RTX/RTTTL Ringtones
Ring Tones Text Transfer Language (RTTTL) ringtones are an older format of ringtones that many handsets support but which are not as popular these days as real tones (MP3's and WAV files). They are textual and look like fifth:d=4,o=5,b=63:8P,8G5,8G5,8G5,2D#5. To send these use SubmitMessage.Message.Ringtone.

OTA Bitmap Picture Messages
OTA bitmap picture messages are an older form of image, often associated with black and white handsets. To send these use the SubmitMessage.Message.PictureMessage.

Group Graphics
OTA bitmap group graphics are an older form of image, often associated with black and white handsets. Group Graphics are displayed when the caller is stored as a member of a particular group- e.g. friends or office. To send these use SubmitMessage.Message.GroupGraphic

Operator Logo's
OTA bitmap operator logo's are an older form of image, often associated with black and white handsets. Operator logos are shown when the phone is not in use but in contact with the network. To send these use SubmitMessage.Message.OperatorLogo.

Images
To send single images (sometimes called wallpapers) such as JPEG, GIF, WBMP and PNG you should use a WAP Push. If you want to send the image to the messaging server and for it to then serve it to the handset (recommended) you should use SubmitMessage.Message.WAPPush.FileUpload. This returns a library number so you can resend the same image multiple times and supports content adaption (see below). However, if you want to serve the image from your own server then use SubmitMessage.Message.WAPPush.si with the URL of your image.

Audio
To send single audio files (such as MP3's, WAV files) you should use WAP Push. If you want to send the audio to the messaging server and for it to then serve it to the handset (recommended) you should use SubmitMessage.Message.WAPPush.FileUpload. This returns a library number so you can resend the same audio multiple times. However, if you want to serve the audio from your own server then use SubmitMessage.Message.WAPPush.si with the URL of your audio.

Video
To send single video files (such as 3gp) you should use probably WAP Push as it works with more handsets at the current time. If you want to send the video to the messaging server and for it to then serve it to the handset (recommended) you should use SubmitMessage.Message.WAPPush.FileUpload. This returns a library number so you can resend the same video multiple times. However, if you want to serve the video from your own server then use SubmitMessage.Message.WAPPush.si with the URL of your video.

Multimedia (MMS)
To send true multimedia presentations (files involving text, images and audio with the .mms extension) you must use SubmitMessage.Message.MMSNotification.FileUpload. This returns a library number so you can resend the MMS multiple times and you also benefit from content adaption (see below).

Java (J2ME) Applications
To deliver Java applications (.JAR) to the handset you should use SubmitMessage.Message.WAPPush.FileUpload. However if you wish to deliver the descriptor file (.JAD) first you must use SubmitMessage.Message.WAPPush.si with the URL of your JAD file. The JAD file must then contain the URL for the JAR file.

Protocol Data Unit
By using PDU's you can have much greater control and flexibility over the data that you send to the mobile phone. A common use of PDU's is to deliver Over-The-Air (OTA) programming messages, but they can also be used to send messages such as ringtones. However they are not suitable for anyone without a strong technical background in their usage. If you don't know that a PDU is and what you should populate the SOAP packet with, then you should not be using them. To send your own PDU's use SubmitMessage.Message.SmsSubmitPdu.

Content Adaption

Different phones have different capabilities: some have small low definition colour screens other have large colour screens; some can play complex polyphonic ringtones, other can only play simple poly tones and other cannot play poly tones at all. Some can display .gif images, others cannot. As a result it is not realistic to product a single mms file that will work on many phones.

The solution is to adapt the content just before delivering it to the phone. This is a complex process that involves breaking down the original mms file into its component parts, including the list of recipients, and reformatting each part before re-assembling the mms file and delivering it to the phone. All this has to be done as soon as the phone requests the content and before we deliver the content to the phone. Another significant advantage of Repurposing is often that we can deliver small files to most phones - even if you provide us with a large image.

You can send a .mms file or any other file such as .jpg .gif .wbmp .midi .wav .amr .jad etc. We will adapt image files with the .jpg .gif .png and .wbmp extensions to suit the recipients handsets. Other content, such as OTA bitmaps, sound files, and video will currently be passed unchanged. You can disable this using the DisableRepurposing element as described below.

Our servers are aware of the capabilities and limitations of thousands of phones and can adapt your content so that you can reach the maximum number of recipients without problems.

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 interest. There are 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 + prefix indicates a complex type, while the identing and - 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	Description
+ SubmitMessage
- Username	Required. An alphanumeric string with a maximum size of 20 characters e.g. ANOther.61234
- PIN	Required. An alphanumeric string with a maximum size of 20 characters e.g. 123456
+ Recipient	Optional. This is a wrapper for all the information about the recipient including their phone number and make and model of their phone. Not all fields are required all the time and if you are just uploading content you will not need this at all.
- SendTo	Optional. 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 (To, Cc and Bcc together) but you can submit as many requests as you need, in series or in parallel.
- SendCc	MMS Only. Optional. The number of the phone(s) that you wish to send the MMS content as Cc recipients to. The number should be in full International Format, including the Country Code. For example 447700912345 for a UK mobile. You can put more than one number in here in which case you should separate the numbers with a comma - for example 447700912345,447700912346. We suggest that you do not put more than 350 numbers in each request (To, Cc and Bcc together) but you can submit as many requests as you need, in series or in parallel.
- SendBcc	MMS Only. Optional. The number of the phone(s) that you wish to send the MMS content as Bcc recipients to. The number should be in full International Format, including the Country Code. For example 447700912345 for a UK mobile. You can put more than one number in here in which case you should separate the numbers with a comma - for example 447700912345,447700912346. We suggest that you do not put more than 350 numbers in each request (To, Cc and Bcc together) 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
- SendCcAddressBook	MMS Only. Optional. You can specify the name of your Address Book to use as the list of Cc 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
- SendBccAddressBook	MMS Only. Optional. You can specify the name of your Address Book to use as the list of numbers to Bcc 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
- PhoneMake	Optional. For sending monophonic ringtones only. One of Ericsson, Motorola, Nokia, Sagem, Sony or EMS. EMS is a catch-all for EMS compatible handsets. This is not case sensitive.
- PhoneModel	Optional. For sending monophonic ringtones only. The model number - e.g. 6210, 7650, Treo, V70, T68i, P800, etc. This is not essential at this stage but may be required in the future as we provide more in-depth support for specific handsets.
- MCC	Optional. For sending operator logo's only. Mobile Country Code. Each mobile operator has a unique MCC and MNC. You must quote the correct MNC and MCC for the destination handsets which can be found in the coverage tables.
- MNC	Optional. For sending operator logo's only. Mobile Network Code. Each mobile operator has a unique MCC and MNC. You must quote the correct MNC and MCC for the destination handsets which can be found in the coverage tables.
+ SendOptions	Optional.These are options which affect the way a message is delivered. See below for details of what these can be and how they affect the message.
- 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).
- DisableRepurposing	MMS Only. Optional. By default, repurposing of MMS images is always on (i.e. the same as setting this to false). This enables you to switch off this rule by setting it to true.
- DisableWalledGardenRule	MMS Only. Optional. By default, we will send messages to known walled-garden networks using WAP Push even if you specify MMS notification (i.e. the same as setting this to false). This enables you to switch off this rule by setting it to true.
+ Message	Required. The Message element is essentially just a wrapper and you will need to define the type of message using the appropriate elements within it as shown below.
+ Ringtone	An RTTTL or RTX monophonic ringtone. Ringtones can be sent to several makes of phones.
- LibraryNumber	The five digit library number for the ringtone you want to send. You must either own the ringtone (by having uploaded it previously) or it must be public. If you use a LibraryNumber you must not also try to submit a Data section at the same time.
- Data	A RTTTL or RTX string. It will be uploaded to the library as a private entry, given a unique library number, and then sent. If you submit your own ringtone Data you must not try to use a LibraryNumber at the same time.
- Format	This should be RTTTL for a ringtone.
+ PictureMessage	The message is an OTA bitmap image picture message with an optional TextMessage.
- LibraryNumber	The five digit library number for the picture message you want to send. You must either own the picture message (by having uploaded it previously) or it must be public. If you use a LibraryNumber you must not also try to submit a Data section at the same time.
- Data	The OTA bitmap string. It will be uploaded to the library as a private entry, given a unique library number, and then sent. If you submit your own picture message Data you must not try to use a LibraryNumber at the same time.
- Format	Currently the only format is OTA.
+ OperatorLogo	The message is an OTA bitmap operator logo. Operator logos are shown when the phone is not in use but in contact with the network.
- LibraryNumber	The five digit library number for the operator logo you want to send. You must either own the operator logo (by having uploaded it previously) or it must be public. If you use a LibraryNumber you must not also try to submit a Data section at the same time.
- Data	A OTA bitmap string. It will be uploaded to the library as a private entry, given a unique library number, and then sent. If you submit your own operator logo Data you must not try to use a LibraryNumber at the same time.
- Format	Currently the only format is OTA.
+ GroupGraphic	This message is a group graphic. Group Graphics are displayed when the caller is stored as a member of a particular group- e.g. friends or office.
- LibraryNumber	The five digit library number for the group graphic you want to send. You must either own the graphic (by having uploaded it previously) or it must be public. If you use a LibraryNumber you must not also try to submit a Data section at the same time.
- Data	A OTA bitmap string. It will be uploaded to the library as a private entry, given a unique library number, and then sent. If you submit your own group graphic Data you must not try to use a LibraryNumber at the same time.
- Format	Currently the only format is OTA.
+ SmsSubmitPdu	The message a PDU with user defined Data Coding Scheme, Protocol Identifier, User Data Header and User Data.
- DataCodingScheme	Part of the PDU. A single byte.
- ProtocolIdentifier	Part of the PDU. A single byte.
- UserData	Part of the PDU. A binary string.
- UserDataHeader	Part of the PDU. A binary string.
+ WAPPush	Indicates that you want to send a WAP PUSH message.
- SimplePush	Deprecated. Use LibraryNumber (see below) instead.
+ LibraryNumber	Indicates that you wish to send MMS content from the library via WAP Push. You must either own the file (by having uploaded it previously) or it must be public. If you use a LibraryNumber you must not also try to submit another section at the same time.
- LibraryNumber	The five digit library number for the MMS you want to send.
- TextMessage	The text message you want to include with the MMS message. This has a maximum of 50 characters.
+ FileUpload	Indicates that you wish to upload (and optionally send) MMS content using file data submitted in the SOAP request as a WAP PUSH. To just upload a file and get back a LibraryNumber for it, do not include a Recipient section.
- FileName1	The full name of the file plus extension. eg. smiley.gif
- FileData1	The contents of the file named above (raw data)
- FileType1	The type of the file. This is currently only of use for polyphonic ringtones where is should be polyX where X is 1 to 32 and indicates the number of channels the polyphonic ringtone uses. For all other content, leave this blank, null or omitted.
- FileTitle1	The title of the file.
- TextMessage1	The Subject of the WAP Push
- ContentType1	Optional. You can specify the MIME type for the data you are sending. If you do not specify it, it will be determined from the filename extension given in FileName1. This will work for most content, but since only the most basic type is selected for each known extension, you have greater control if you specify it.
+ si	For those who need to create their own WAP PUSH Service Indication (si) messages we offer this API. If you are just uploading content to send use the FileUpload interface.
- href	Required. A text string specifying the URI indicating the service.
- si-id	Recommended. A text string identifier that is used to distinguish between different WAP PUSH SI's with the same href. Note: if you do not include an si-id then two SI's with the same si-href with appear to be the same to the handset and may well be discarded silently by it, even though it returns a sucess status delivery receipt. si-id's are highly recommended, therefore.
- created	Recommended. A date in the format YYYY-MM-DDThh:hh:ss for timezone UTC. The date and time of creation or last modification of the content indicated by the si-href.
- si-expires	Recommended. A date in the format YYYY-MM-DDThh:mm:s for timezone UTC. Specified the date and time when the SI auotmatically expires and is deleted (or marked as expired) on the recipients handset.
- action	Optional. A text string specifying the action to be take. It can any one of signal-none, signal-low, signal-medium, signal-high, or delete. The default is signal-medium when no action is specified, which is the recommended setting.
- content	Recommended. A text string that will be displayed on the recipients handset when the WAP PUSH message is received.
+ info	Optional. It is very unlikely that you will need to use the info/item section and can omit it.
+ item	The info tag item pairs (pcdata and class) are for specifying additional information not provided by the others.
- pcdata	The info tags are for specifying additional information not provided by the others. At present you can only have one pair of these tags, although the full WAP specification shows multiple instances possible.
- class	The info tags are for specifying additional information not provided by the others. At present you can only have one pair of these tags, although the full WAP specification shows multiple instances possible.
+ MMSNotification	Indicates that you want to send an MMS notification. The elements descibe the type of MMS content.
- LibraryNumber	Indicates that you wish to send MMS content from the library. You must either own the file (by having uploaded it previously) or it must be public. If you use a LibraryNumber you should not also try to submit another section at the same time.
- FileUpload	Indicates that you wish to upload (and optionally send) MMS content using file data submitted in the SOAP request as an MMS Notification. To just upload a file and get back a LibraryNumber for it, do not include a Recipient section.
- FileName1	The full name of the file plus extension. eg. smiley.mms
- FileData1	The contents of the file named above (raw data).
- FileType1	The type of the file. This is currently only of use for polyphonic ringtones where is should be polyX where X is 1 to 32 and indicates the number of channels the polyphonic ringtone uses. For all other content, leave this blank, null or omitted.
- FileTitle1	The title of the file.
- TextMessage1	The Subject of the MMS
- 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	Description
+ SubmitMessageResponse
- Text	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.
- Report	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.
- MessageIdentifier	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.
- Reserved	This whole section is reserved for use by Connection Software and should be ignored when parsing responses.

Example SOAP Requests

Note that in the examples below the SOAP packet may have been split over multiple lines and so may contain invalid whitespace.

RTTTL (Ringtone) Message

This SOAP packet sends the Monty Python theme tune as an RTTTL ringtone string.

<?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 encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<ns2:SubmitMessage>
<Username xsi:type="xsd:string">ANOther.61234</Username>
<PIN xsi:type="xsd:string">123456</PIN>
<Recipient xsi:type="ns2:Recipient">
<SendTo xsi:type="xsd:string">447009123456</SendTo>
<PhoneMake xsi:type="xsd:string">Nokia</PhoneMake>
<PhoneModel xsi:type="xsd:string">6210</PhoneModel>
</Recipient>
<Message xsi:type="ns2:Message">
<Ringtone xsi:type="ns2:SmartMessage">
<Data xsi:type="xsd:hexBinary">
4D6F6E7479507974686E3A643D342C6F3D352C623D3230303A66362C3865362C64362C386323
362C63362C38622C61232C38612C38672C38612C3861232C612C38672C3263362C38702C3863
362C38612C38702C38612C38612C3867232C38612C3866362C38702C3863362C3863362C3870
2C38612C3861232C38702C3861232C3861232C38702C3863362C3264362C38702C3861232C38
672C38702C38672C38672C3866232C38672C3865362C38702C3864362C3864362C38702C3861
232C38612C38702C38612C38612C38702C3861232C326336
</Data>
<Format xsi:type="ns2:DataFormat">RTTTL</Format>
</Ringtone>
</Message>
</ns2:SubmitMessage>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Image from the library (WAP PUSH)

You can also upload content to our library (for public or private use) and send it by referencing it's returned library number. For example, to send the Connection Software logo, as shown at the top of this page, you would send this request.

Image from the library (MMS Notification)

This send the same Connection Software logo using an MMS notification.

Upload an image to the library and send (WAP PUSH)

Upload a smiley face image to the library, getting back the library number for future sends, but also sending the image to a number. Note the FileData element broken over several lines for readability but should not be broken in your SOAP packet.

<?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 encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<ns2:SubmitMessage>
<Username xsi:type="xsd:string">ANOth.12345</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">
<WAPPush xsi:type="ns2:WAPPush">
<FileUpload>
<FileName1>smiley1.gif</FileName1>
<FileData1>47494638396120002000B30000000000990000009900999900000099990099009999999999CCCCCCFF
000000FF00FFFF000000FFFF00FF00FFFFFFFFFF21F9040100000F002C000000002000200040049EF0C94925B8F8D63DC1F
AE07785A2478A16699E2CB8A2CFA826746DBF2587B72C50ED2E4C28C3F3013348644F072CFA38BFE649038DF1AE2A4A93189
44DADA5973738F48EC9D833EA986C2FB553DBED5BEDA8C375A8B047CD5BA47C7580580B4F5A838485865B7B615B297C635C5F
262B958D8A32962543893D65539E22536C6D6E9491A6982E1D7C3517AF473F717273593AA449748288397E1BA67E1100003B</FileData1>
<FileType1></FileType1>
<FileTitle1>smiley</FileTitle1>
<ContentType1></ContentType1>
</FileUpload>
</WAPPush>
</Message>
</ns2:SubmitMessage>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

WAP Push Service Indication (SI)

The example below shows how to send a WAP Push service indication message to a phone with the URL of your content to be downloaded.

If you need to send your own URL's, for example to point to content on your own servers, then this is the interface for you.

<?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 encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<ns2:SubmitMessage>
<Username xsi:type="xsd:string">ANOther.12345</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">
<WAPPush xsi:type="ns2:WAPPush">
<si xsi:type="ns2:si">
<indication xsi:type="ns2:indication">
<href xsi:type="xsd:anyURI">http://www.mycompany.com/images/logo.jpg</href>
<created xsi:type="xsd:dateTime">2003-12-11T11:42:00</created>
<content xsi:type="xsd:string">Here is your picture from MyCompany.Com Enjoy!</content>
</indication>
</si>
</WAPPush>
</Message>
</ns2:SubmitMessage>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Protocol Data Unit (PDU) Message

By using PDU's you can have much greater control and flexibility over the data that you send to the mobile phone. A common use of PDU's is to deliver Over-The-Air (OTA) programming messages, but they can also be used to send messages such as ringtones. However they are not suitable for anyone without a strong technical background in their usage. If you don't know that a PDU is and what you should populate the SOAP packet below with, then you should not be using them.

This example sends a ringtone.

POST /sendsms5 HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: text/soap; charset="utf-8"
Content-Length: 1153

<?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 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</SendTo>
</Recipient>
<ReplyTo>csoft.co.uk</ReplyTo>
<Message xsi:type="ns2:Message">
<SmsSubmitPdu xsi:type="ns2:SMS_SUBMIT_PDU">
<DataCodingScheme xsi:type="xsd:hexBinary">15</DataCodingScheme>
<ProtocolIdentifier xsi:type="xsd:hexBinary">7D</ProtocolIdentifier>
<UserDataHeader xsi:type="xsd:hexBinary">06050415810000</UserDataHeader>
<UserData xsi:type="xsd:hexBinary">024A3A51D195CDD004001B20550590610560558550548540820849900000</UserData>
</SmsSubmitPdu>
</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</MessageIdentifier>
<Report xsi:type="xsd:int">-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">
<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 accepted for procesing. 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</MessageIdentifier>
<Report xsi:type="xsd:int">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 automatrically 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.

SMS This page was last modified at 10:18 UTC on Wednesday January 25, 2012