|
Sending Multimedia Messages Web Service
HTTP(S) API
Use the firewall and proxy server friendly HTTP protocol to send multimedia content, such as images, ringtones, MMS, and J2ME MIDlets to mobile/cell phones. The HTTP API is quick and simple to integrate with most modern programming and scripting languages. 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 binary file image.jpg would look something like this:
POST /webservices/http/sendmms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Content-Length: 3458
Username=ANOther.12345&PIN=123456&SendTo=447700912345
&Message=Hello%20World
&WAPPushFileName1=image.jpg&WAPPushFileData1=.......
(Note that in the above example the POST body has been split over multiple lines to make it more readable. In practice the body must be one continuous string.)
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/sendmms
http://www.csoft.co.uk/webservices/http/sendmms
Secondary Server
https://www2.csoft.co.uk/webservices/http/sendmms
http://www2.csoft.co.uk/webservices/http/sendmms
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 encode plain ASCII text messages that contain certain special characters.
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/sendmms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Connection:close
Content-Length: 70
Username=ANOther.12345&PIN=123456&Message=%D7%90&SendTo=447700912345
Choosing The Right Message Type
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 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 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 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 OperatorLogo.
vCards & vCalendars
These are electronic formats for exchanging business cards and calendar entries respectively.
To send these use the vCard and vCal tags.
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 WAPPushFileName1 & WAPPushFileData1. 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 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 WAPPushFileName1 & WAPPushFileData1si with the URL of your audio.
Video
To send single video files (such as 3gp) we recommend you use 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 (also recommended) you should use
WAPPushFileName1 & WAPPushFileData1si with the URL of your video.
Multimedia (MMS/SMIL)
To send true multimedia presentations (files involving text, images and audio with the .mms extension) you must use
MMSNotificationFileName1 & MMSNotificationFileData1. This returns a library number so you can resend the MMS multiple times and you also
benefit from content adaption (see below). Note that you can also submit a ZIP file of the components of your MMS this way and we will compose the MMS file
for you (see the example below).
Java (J2ME) MIDlets
To deliver Java applications (.JAR) to the handset you should use WAPPushFileName1 & WAPPushFileData1si 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 what a PDU is and what you should populate the fields with, then you should not be using them. To send your own
PDU's use the SmsSubmitPdu tags.
Creating MMS Files
There are various toolkits available now which allow you to compile the components of an MMS into a single .mms file. Many of them allow you to use simple drag and drop interfaces with preview so they are ideal for anyone to use. However, if you do not know how to compile multiple items (audio, video, text, SMIL) into a single MMS file, or need a programmatic solution to bring the components together, you can just submit a ZIP file instead and our server will create the MMS for you. See the example below for more details.
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 into a suitable format 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 content adaption is often that we can deliver smaller 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.
Parameter Description
| Tag | Required | Description |
|---|---|---|
| General | ||
| Username | Required | This was sent to your email and looks something like ANOther.61234 |
| PIN | Required | This was sent to your mobile/cell phone and looks something like 123456 |
| ReplyTo | Optional | If you have two-way service numbers then you can set the ReplyTo (MSISDN) that the message appears to come from. You can also use the PermittedReplyTo query to determine which numbers are available to you. |
| SendTo | Typically required | The number of the phone that you wish to send 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. |
| 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 |
| DeliveryServiceOption | Optional | Specifies the type of delivery service you wish to use to deliver the message. The values are ‘Default’, ‘Premier’ or ‘Economy’ (case insensitive). When not specified, an unrecognized value is passed, or ‘Default’ is selected, the setting on your website account is used. |
| SendTimeDelay | Optional | Specifies the number of minutes that the message should be delayed. The value must be between 1 minute and 10080 minutes (7 days). |
| SendTimeAbsolute | Optional | Specifies the date and time that you want the message to be sent. This must be in UTC (GMT). The format is ISO 8601 (excluding timezone offset). i.e. YYYY-MM-DDTHH:MM:SS |
| ResponseFormat | Optional | Allows you to control the format of the response for easier parsing. See ResponseFormat lower down this page |
| Picture Message | ||
| PictureMessage | Required | The Picture Message library number or hex encoded OTA bitmap data. PictureMessage numbers are in the range 20000 to 29999. |
| Group Graphic | ||
| GroupGraphic | Required |
Group Graphic library number or hex encoded OTA bitmap data. Group Graphic library numbers are in the range 10000 to 19999. The PhoneMake should be set to Nokia as currently you can only send Group Graphics to Nokia phones |
| PhoneMake | Required | Nokia |
| Operator Logo | ||
| OperatorLogo | Required | The Operator Logo library number or hex encoded OTA bitmap data. Operator logo library numbers are in the range 10000 to 19999. |
| MCC | Required | Mobile Country Code. This must be set to the correct value for the mobile phone network you normally connect to . See our operator list to find the right value. |
| MNC | Required | Mobile Network Code. This must be set to the correct value for the mobile phone network you normally connect to . See our operator list to find the right value. |
| RTTTL Ringtone | ||
| Ringtone | Required | Monophonic ringtone library number OR Hex encoded RTTTL or RTX string. Special characters, such as <comma>, must be encoded according to the HTTP specification. For <comma> use %2C, for <colon> use %3A, for <equals> use %3D. See Encoding Characters. |
| vCard | ||
| vCard | Required | The URL encoded vCard data.. |
| vCalendar | ||
| vCal | Required | The URL encoded vCal data.. |
| PhoneMake | Required | One of Alcatel, Ericsson, Motorola, Nokia, Sagem, Siemens, or EMS. Note that not all phones can receive ringtones and group graphics and that some phones have rather limited capabilities. |
| PhoneModel | Optional | 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. |
| MMS Notification | ||
| MMSFileMMS | Either | A number that references an MMS file held in the content library for delivery by MMS Notification. The MMS file must either be public, or you must own it. MMS file library numbers are in the range 80000 to 89999. |
| MMSNotificationFileName1 | Either | The filename and extension of the MMS file that will be delivered to the phone using MMS Notification. Typically this is .mms though you can use a .zip file too (see example below). Filename and extension are limited to 50 characters in total. |
| MMSNotificationFileData1 | Required | Required if using MMSNotificationFileName1. The actual hex encoded contents of the MMS file named in MMSNotificationFileName1 above. |
| SendCc | Optional | The number of the phone(s) that you wish to send 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. |
| SendBcc | Optional | The number of the phone(s) that you wish to send 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. |
| SendCcAddressBook | 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 | Optional | You can specify the name of your Address Book to use as the list of Bcc 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 |
| Message | Optional | Contains a message that will be displayed to the recipient. Typically the message invites the recipient to view the image, listen to the music or install the java program. For MMS messages this is the Subject that the recipient sees, for WAP Push, the message. A maximum of 50 characters may be sent - less if the message is Unicode encoded. Special characters, such as <space>, must be encoded according to the HTTP specification. See Encoding Characters. Note that if you are creating your own WAP PUSH service indication messages using the "si-" tags below, you must use the si-content tag, not this Message tag. |
| ContentType | 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 the MMSNotificationFileName1 or WAPPushFileName1 tag. This is often OK, but since only the most basic type is selected for each known extension, you have greater control if you specify it. |
| DisableRepurposing | Optional | By default, repurposing (also known as content adaption) of MMS images is always on (i.e. the same as setting this to 0). This enables you to switch off this rule by setting it to 1. |
| DisableWalledGardenRule | 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 0). This enables you to switch off this rule by setting it to 1. |
| AddSMIL | Optional | Some handsets work better if a SMIL section is added to the MMS, even for a simple item such as a image. You can control this by setting the value to either 0 (default for handset, if known), 1 (add SMIL) or 2 (do not add SMIL). If you do not know what this should be we recommend not setting it. However, if you think it may help with a problem you are experiencing, please contact us to discuss it. |
| WAP PUSH | ||
| MMSFileWAP | Required | A number that references a file held in the content library for delivery by WAP PUSH. The file must either be public, or you must own it. File library numbers are in the range 80000 to 89999. |
| WAPPushFileName1 | Required | The filename and extension of the file that will be delivered to the phone using WAP Push. It is essential that the extension is appropriate for the content you wish to deliver. Typical file extensions are .jpg, .gif, .png and .jar - though some handsets support many other file types. Filename and extension are limited to 50 characters. |
| WAPPushFileData1 | Required | Required is using WAPPushFileData1. The hex encoded contents of the file named above in WAPPushFileName1. |
| Message | Optional | Contains a message that will be displayed to the recipient. Typically the message invites the recipient to view the image, listen to the music or install the java program. For MMS messages this is the Subject that the recipient sees, for WAP Push, the message. A maximum of 50 characters may be sent - less if the message is Unicode encoded. Special characters, such as <space>, must be encoded according to the HTTP specification. See Encoding Characters. Note that if you are creating your own WAP PUSH service indication messages using the "si-" tags below, you must use the si-content tag, not this Message tag. |
| ContentType | 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 the MMSNotificationFileName1 or WAPPushFileName1 tag. This is often OK, but since only the most basic type is selected for each known extension, you have greater control if you specify it. |
| DisableRepurposing | Optional | By default, repurposing of MMS images is always on (i.e. the same as setting this to 0). This enables you to switch off this rule by setting it to 1. |
| DisableWalledGardenRule | 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 0). This enables you to switch off this rule by setting it to 1. |
| WAP PUSH Service Indication | ||
| si-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 success status delivery receipt. si-id's are highly recommended, therefore. |
| si-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 ISO format YYYY-MM-DDTHH:mm:SS for timezone UTC. Specified the date and time when the SI automatically expires and is deleted (or marked as expired) on the recipients handset. |
| si-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. |
| si-content | Recommended | A text string that will be displayed on the recipients handset when the notification is received. |
| si-info-pcdata | Optional | 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. |
| si-info-class | Optional | 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. |
| Protocol Data Unit (PDU) | ||
| SmsSubmitPduDataCodingScheme | Required | The data coding scheme to use, as a hex encoded binary string. |
| SmsSubmitPduProtocolIdentifier | Required | The protocol identifier to use, as a hex encoded binary string. |
| SmsSubmitPduUserDataHeader | Required | The user data header to use, as a hex encoded binary string. The format of the UDH is <UDH length><ports specification format><port digits length><destination port><source port>. |
| SmsSubmitPduUserData | Either | The user data to use, as a hex encoded binary string. |
| Message | Either | The text message that will be incorporated into the PDU as the user data instead of specifying and encoding it yourself. |
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
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
| Parameter | Type | Size | Description |
|---|---|---|---|
|
MessageIdentifier |
string | 15 | A unique identifier for the message. You can use this to match against the message history and/or delivery receipts. |
| Report | numeric | 3 | A report code |
| Text | string | 255 | Any descriptive text associated with the response. This is optional, may be left out or be blank and is subject to change without notice. |
| LibraryNumber | numeric | 5 | If you submit a file for delivery, using the MMSNotificationFile... or WAPPushFile... tags then the unique library number for that file with be returned in the response for your future reference. |
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.
Examples
You can download free sample code in many of the most common programming languages to get you started.
Sending an image/wallpaper using WAP PUSH
barcode.jpg
This sends the above JPEG image (a barcode) named barcode.jpg as a WAP PUSH.
POST /webservices/http/sendmms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Connection:close
Content-Length: 2875
Username=ANOther.12345&PIN=123456&SendTo=447700912345
&Message=Your%20barcode%20ticket
&WAPPushFileName1=barcode.jpg
&WAPPushFileData1=FFD8FFE000104A46494600010101006000600000FFDB00
43000302020302020303030304030304050805050404050A070706080C0A0C0C0B
0A0B0B0D0E12100D0E110E0B0B1016101113141515150C0F171816141812141514
FFDB00430103040405040509050509140D0B0D1414141414141414141414141414
141414141414141414141414141414141414141414141414141414141414141414
141414FFC0001108000B006003012200021101031101FFC4001F00000105010101
01010100000000000000000102030405060708090A0BFFC400B510000201030302
0403050504040000017D01020300041105122131410613516107227114328191A1
082342B1C11552D1F02433627282090A161718191A25262728292A343536373839
3A434445464748494A535455565758595A636465666768696A737475767778797A
838485868788898A92939495969798999AA2A3A4A5A6A7A8A9AAB2B3B4B5B6B7B8
B9BAC2C3C4C5C6C7C8C9CAD2D3D4D5D6D7D8D9DAE1E2E3E4E5E6E7E8E9EAF1F2F3
F4F5F6F7F8F9FAFFC4001F01000301010101010101010100000000000001020304
05060708090A0BFFC400B511000201020404030407050404000102770001020311
04052131061241510761711322328108144291A1B1C109233352F0156272D10A16
2434E125F11718191A262728292A35363738393A434445464748494A5354555657
58595A636465666768696A737475767778797A82838485868788898A9293949596
9798999AA2A3A4A5A6A7A8A9AAB2B3B4B5B6B7B8B9BAC2C3C4C5C6C7C8C9CAD2D3
D4D5D6D7D8D9DAE2E3E4E5E6E7E8E9EAF2F3F4F5F6F7F8F9FAFFDA000C03010002
110311003F00E9BF66CF8A5E2EF1178ABC4D0DEF89753BE8EDFC37E2EB98CDDDDC
921492DF5182289D4B1246C566000E067DEBD0FC31E38D7EF3C1D697136AB74D30
9B59065329DD88F4B8658C67A9C3BB1FC6BC43F662516FAFF8A1E3CABBF867C6C8
C73D41D46D491F9935EA3E1D262F87762C8705AE35904FB1D32DD4FE9C5007A07C
28F16EBFAC7C0EB0BFBBD4EE66BB6F0A4D706692662C5FFB1B4E9779E7AEE91DBE
AC6BC07FE16CF8C078CFE0E5BAF8A35930EA7A1A4F7713DEB94B87FB1E98DB9C67
0C73339E7FBC6BD93E073B3FECF76458924784E541FEEFF62E9EB8FC940FC2BC0D
6C60FF0084D7E05BECF98786830393D458E978FE42803DDFC5FE39F1259F8BBE2C
C70EAF771C7A75807B609332889BFE11A79F2A0743E600DF5AE2BF66EF89DE2BD7
7E154D7D77E21D4EFEE7ECBE1991A5BBBA791879C6E7CC20939F9B62823DAB77C7
A36F8B3E3211C17D2D8B7BFF00C52F22FF002E2B81FD97A2587E0F5FAA0C016BE1
051CF6FF0048FF00E28FE7401CEDF7C5AF194BF0EB50B93E2BD68CA2363BC5FCBC
E65D0148C6EF4B89BF09187739EBFC5DF127C57A6FECC5F0EF5CB7F13EAF0EA57D
77E1D49EEE3BD956497CDBED41640C4364EE112E7E95C0C3A5DB4BF0E7508DE2CA
796DC6E3FF003D3C3A7D7FD91F9575DE2DB1827FD90BE17874DC1751F0C81C9E31
A86A38FF00D08FE7401EB5F08BC73E23D6BC23717175AC5E4F3FFC2C1B6D37CE96
762DE4359D83940739037393C77AF9CFE077C6AF1B7883C3BF03A4D43C5DAE5D3E
B50F8D1EF8CB7D211706DB4E8E484B8CE0EC62580AF75F84CA2D7C19388BE407E2
3D9C9D7F8BFB3EC39FD057CDFF00B3D6996CBE19FD9F7117FAB87C7017E63C06D2
63DDDFBD007D47E1AF1C7892F3C53676D3EAF7535BC9F0BFC43A9346656C19E2D4
E24493AFDE00903DABC72E7E2F78CA0F8F1E39D317C53AB1B2B3B0F0D4B15B7DB2
4088D3E9B1BCACA33D589AF45F0831FF008584B1E4EC8FE157896351E8A7564C8F
D05788DFC29FF0D13E3C6C7CD2697E19DC73D76E969B7F2C0A00FFD9
(Note that in the above example the query string has been split over multiple lines to make it more readable. In practice the query string must be one continuous string.)
Sending an image/wallpaper using MMS
smiley1.gif
This sends the above GIF image (a smiley face) named smiley1.gif as an MMS message.
POST /webservices/http/sendmms HTTP/1.1
Host: www.csoft.co.uk
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Connection:close
Content-Length: 613
Username=ANOther.12345&PIN=123456&SendTo=447700912345&Message=Hello
&MMSNotificationFileName1=smiley1.gif
&MMSNotificationFileData1=47494638396120002000B3000000000099000000990099990000009999
0099009999999999CCCCCCFF000000FF00FFFF000000FFFF00FF00FFFFFFFFFF21F904010000
0F002C000000002000200040049EF0C94925B8F8D63DC1FAE07785A2478A16699E2CB8A2CFA8
26746DBF2587B72C50ED2E4C28C3F3013348644F072CFA38BFE649038DF1AE2A4A9318944DA
DA5973738F48EC9D833EA986C2FB553DBED5BEDA8C375A8B047CD5BA47C7580580B4F5A83
8485865B7B615B297C635C5F262B958D8A32962543893D65539E22536C6D6E9491A6982E1D7C
3517AF473F717273593AA449748288397E1BA67E1100003B
(Note that
in the above example the query string has been split over
multiple lines to make it more readable. In practice
the query string must be one continuous string.)
Sending a library image/wallpaper using MMS
You can also reference content held in your library using it's library number. This sends the Connection Software logo (held in the public library) as shown at the top right of this page.
POST /webservices/http/sendmms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Connection:close
Content-Length: 115
Username=ANOther.12345&PIN=123456&SendTo=447700912345
&Message=Connection%20Software
&MMSFileWAP=8005&ResponseFormat=1
Sending a URL using a WAP Push Service Indication Message
The Service Indication (SI) provides the ability to send notifications
to recipients in an asynchronous manner. In it's simplest form, an SI contains
a short message (content) and a URI indicating a service. When the recipient
receives the notification they can either start the service indicated by the
URI, or save it on the handset for later activation.
The short message sent with the notification should be something that helps
the user understand what the notification is about and why they should therefore
open it.
| Parameter | Description |
|---|---|
| si-href | A text string specifying the URI indicating the service. This tag is required. |
| si-id | A text string identifier to distinguish between different 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 success status delivery receipt. si-id's are highly recommended, therefore. |
| si-created | 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 | A date in the format YYYY-MM-DDThh:mm:s for timezone UTC. Specified the date and time when the SI automatically expires and is deleted (or marked as expired) on the recipients handset. |
| si-action | 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. |
| si-content | A text string that will be displayed on the recipients handset when the notification is received. |
| si-info-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. |
| si-info-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. |
POST /webservices/http/sendmms HTTP/1.1
Host: 127.0.0.1:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Connection:close
Content-Length: 165
Username=ANother.12345&PIN=12345678&SendTo=447700912345&si-href=http://www.csoft.co.uk/images/smiley1.gif&si-content=Connection%20Software
Sending an MMS as a ZIP file
If you want to send an MMS message but don't want, or know how, to compile an MMS file, you can submit the component parts (images, audio, smil, and text) as separate files compressed into a single ZIP file. Our messaging server will unzip the file, compile the MMS from it and then send it for you. It will even upload it into your private online library for repeat sending.
The following example shows how to send a long text message as an MMS. The zip file (MLuther.zip) contains two files - a text file named luther.txt and a SMIL file named luther.smil.
luther.txt:
"I have a dream that my four little children will one day live in a nation where they will not be judged by the color of
their skin but by the content of their character." - Martin Luther King, Jr., Address at March on Washington for Jobs and
Freedom, August 28, 1963
luther.smil:
<smil>
<body>
<par dur="20s">
<text src="cid:luther.txt"/>
</par>
</body>
</smil>
These are then compiled into a zip file, hex encoded and inserted into an HTTP to MMS request. You could use our free download to do the hex encoding.
POST /webservices/http/sendmms HTTP/1.1
Host: www.csoft.co.uk
Content-Length: 1092
Connection:close
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Username=ANOther.12345&PIN=11223344&SendTo=447700912345&Message=Luther Quote&MMSNotificationFileName1=MLuther.zip&
MMSNotificationFileData1=504B0304140002000800498134334BE43DD54D000000620000000B000000
6C75746865722E736D696CB329CECDCCB1E3E552B049CA4FA90
431146C0A128B14524A8B6C95
8C0C8A95C0420A3625A915250AC545C9B64AC999295639A52519
A9457A2515254AFA103DFA40
4D6063F4A1E6D8E8434D0600504B0304140002000800C48134331AEDF03FB70000000B0100000A0
000006C75746865722E747874458EB14E04310C447F6574F57212202128699038A0BEDA9B783781A
C2D39CEA1FD7
B7CA2B8CED69B67CFE11D852E0C4236A60D5EC8B1ED5874185A756F8C546A0
B2AF8ADAD418591690F185A953085BC6AD0C2C67180F7FFA0A863667C8FBC72C6BC5F1192363
5E8725DAAA1FFC48579F80D8BB3F82D900A1925673B1E70872F320FE17304347C5459279CEC38E
13547C1DE11E523934AB4C4997A8984C7B8C4CF93CEC125E3CD98B36
E218D7574C7C3F384FB9
7A7C73F504B01021400140002000800498134334BE43DD54D000000620000000B0000000000000001
002000B681000000006C75746865722E736
D696C504B01021400140002000800C48134331AEDF03FB
70000000B0100000A0000000000000001002000B681760000006C75746865722E747874504B05060000
0000020
0020071000000550100000000
(Note that in the above example the query string has been split over multiple lines to make it more readable. In practice the POST body must be one continuous string.)
Sending a mono ringtone using a ringtone library number
POST /webservices/http/sendmms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Content-Length: 85
UserName=ANOther.12345&PIN=123456&SendTo=447700912345&Ringtone=73344
&PhoneMake=Nokia
Sending a mono ringtone using an RTX or RTTTL string
Note that the body line has been broken for formatting, but that this is not an actual line break)
POST /webservices/http/sendmms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Connection:close
Content-Length: 248
UserName=ANOther.12345&PIN=123456&SendTo=447700912345&Ringtone=Uncle%3Ad
%3D8%2Co%3D5%2Cb%3D130%3Aa%2Ca%2Ca%2Cg%2Cf%2Cf%2Cd%2Cf%2C4g%2C4g%2Cc%2Cd%
2C4f%2Ca%2Ca%2C4g%2Cf%2Cf%2Cd%2Cf%2C4g%2C4g%2Cg%2C4f%2C4a%2C4a%2Cg%2C4f%2
C4g%2C4f%2C2f&PhoneMake=Nokia
Sending a Group Graphic library number
POST /webservices/http/sendmms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Content-Length: 89
UserName=ANOther.12345&PIN=123456&SendTo=447700912345&GroupGraphic=10147
&PhoneMake=Nokia
Sending a Group Graphic using a hex encoded Nokia OTA bitmap
Note that the body line has been broken for formatting, but that this is not an actual line break.
POST /webservices/http/sendmms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Connection:close
Content-Length: 344
UserName=ANOther.12345&PIN=123456&SendTo=447700912345&GroupGraphic=00480
e01f83fffffffffffffffe7cfffffffffffffffcfe3fb52aaa2108a9787c1fc0000000000
0107c0f0633cf336ccf30380ea633cdbb6edf90000746366cbf6fd830100796366db76dd8
133986a6b66f336cdbbf93f7d6b7edb36cd99f83e703e66db36cd99f83efa3666db36ccf3
701cfe800000000005b01dfff77d6eaf7bdf&PhoneMake=Nokia
Sending an Operator Logo using a library number
Note that this is one long line but may be displayed on multiple lines.
POST /webservices/http/sendmms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Connection:close
Content-Length: 104
UserName=ANOther.12345&PIN=123456&SendTo=447700912345&OperatorLogo=10147
&MCC=234&MNC=33&PhoneMake=Nokia
Sending an Operator Logo using a hex encoded Nokia OTA bitmap
Note that the body line has been broken for formatting, but that this is not an actual line break.
POST /webservices/http/sendmms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Content-Length: 352
UserName=ANOther.12345&PIN=123456&SendTo=447700912345&OperatorLogo=42f45
000480e01ffffffffffffffffff000000000000000000ffffffffffffffffff0000000000
0000000010f00000000000000000000000000000000000000000000000000000000000000
0000000000000000000000000000000000000000000000000000000000000000000000000
000000000000000000000000000000000000000001&MCC=234&MNC=33&PhoneMake=Nokia
Sending an Picture Message using a library number
POST /webservices/http/sendmms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Connection:close
Content-Length: 112
UserName=ANOther.12345&PIN=123456&Message=Golf%20Course&SendTo=447700912345
PictureMessage=20150&PhoneMake=Nokia
Sending an Picture Message as a hex encoded Nokia OTA bitmap
Note that the body line has been broken for formatting, but that this is not an actual line break.
POST /webservices/http/sendmms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Content-Length: 351
UserName=ANOther.12345&PIN=123456&SendTo=447700912345PictureMessage=42f4
5000480e01ffffffffffffffffff000000000000000000ffffffffffffffffff000000000
00000000010f0000000000000000000000000000000000000000000000000000000000000
0000000000000000000000000000000000000000000000000000000000000000000000000
0000000000000000000000000000000000000000001&PhoneMake=Nokia
Sending a vCard
You can send a vCard (electronic exchange format for business card data) to compatible handsets (such as most Nokia models) very easily using the vCard tag followed by a url encoded vCard definition. The example below sends the phone number for Connection Software to 447700912345. Note that the post body has been split over multiple lines to make it more readable. In practice the body must be one continuous string.
POST /webservices/http/sendmms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Connection:close
Content-Length: 121
Username=ANOTHER.12345&PIN=12345678&SendTo=447700912345&vCard=
BEGIN:VCARD%0D%0AFN:Connection%20Software%0D%0A
TEL:%2B442077138000%0D%0AEND:VCARD
Sending a vCalendar
You can send a vCalendar (electronic exchange format for calendar data) to compatible handsets (such as most Nokia models) very easily using the vCal tag followed by a url encoded vCal definition. The example below sends a meeting calendar entry to 447700912345. Note that the post body has been split over multiple lines to make it more readable. In practice the body must be one continuous string.
POST /webservices/http/sendmms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Connection:close
Content-Length: 381
Username=ANOther.12345&PIN=12345678&SendTo=447700912345&
vCal=BEGIN:VCALENDAR%0D%0AVERSION:1.0%0D%0ABEGIN:VEVENT%0D%0A
CATEGORIES:MEETING%0D%0ASTATUS:TENTATIVE%0D%0A
DTSTART:19960401T033000Z%0D%0ADTEND:20060101T043000Z%0D%0A
SUMMARY:Meeting+with+CSoft%0D%0A
DESCRIPTION:Meeting%20with%20Connection%20Software%20at%20their%20offices%0D%0A
CLASS:PRIVATE%0D%0AEND:VEVENT%0D%0AEND:VCALENDAR
Sending a Protocol Data Unit Binary Message (PDU)
Please note that the ability to send PDU's is intended for those with experience and knowledge of their format and application. We strongly discourage you from using them if you do not fall into this category - you will almost certainly fail to generate a valid PDU. We offer many other API's that should meet your needs in a much simpler and more usable fashion.
This example sends the PDU for a vCard and makes use of the ability to submit a Message string for the user data (SmsSubmitPduUserData) rather than constructing the user data yourself. Note that the post body has been split over multiple lines to make it more readable. In practice the body must be one continuous string.
POST /webservices/http/sendmms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Connection:close
Content-Length: 288
UserName=ANOthER.12345&PIN=12345678&SendTo=447700912345&
SmsSubmitPduDataCodingScheme=00&
SmsSubmitPduProtocolIdentifier=00&
SmsSubmitPduUserDataHeader=06050423F40000&
Message=BEGIN:VCARD%0D%0AVERSION:2.1D%0D%0AN:Smith,John,MD%0D%0ATEL;PREF;VOICE:447700912345%0D%0AEND:VCARD&
ResponseFormat=3
This example sends a text message to a particular port and makes use of the ability to submit a Message string for the user data (SmsSubmitPduUserData) rather than constructing the user data yourself. Note that the post body has been split over multiple lines to make it more readable. In practice the body must be one continuous string.
POST /webservices/http/sendmms HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Connection:close
Content-Length: 233
UserName=ANOther.12345&PIN=12345678&SendTo=447700912345&
&ResponseFormat=3&SmsSubmitPduDataCodingScheme=00&
SmsSubmitPduProtocolIdentifier=00&SmsSubmitPduUserDataHeader=06050450000000&
Message=This%20is%20a%20message%20to%20port%205000