SMS GATEWAY XML SPECIFICATION v1.0 | LAST UPDATED : 06 DECEMBER 2011
print

XML Encoding

When sending XML the first line is usually of the form

<?xml version=”1.0” encoding=encoding_type?>

If this line is omitted then it assumed that the encoding type is UTF-8 which means that extended characters are encoded as such &#xHHHH where HHHH is a hex value

eg. é (dec:130) becomes ‚

If you intend on including extended characters and do not want to encode correctly the best option is to use the ISO-8859-1 character set, which will allow you for the most part to include these extended characters

To specify ISO-8859-1 as the encoding like this

<?xml version=”1.0” encoding=”ISO-8859-1”?>

Please note that the <?xml?> tag is DIFFERENT from the <XML> tag and that the <?xml?> tag should appear before the <XML> tag.

HTTP/S Post Requests

It has been noted that some components do not encode data correctly when performing a POST. The primary reason for this is that the urlencoded encoding is not properly implemented; specifically the encoding of the + character. Any 3rd party component that uses “application/x-www-form-urlencoded” as the content-type should check that the encoding is complete.

With URL encoding certain characters become escaped by using the % character.

These characters include
'*',
'#',
'%',
'<',
'>',
' ',
'[',
']',
'+',
‘&’

For example + is escaped as %2b.

To check if you suffer from this problem send an XML encoded message via a POST with the to set to your number excluding the +country code. e.g. to=”0821234567” and as the text use “test++++test” if it is encoded correctly you will receive the message correctly otherwise you will receive the message as “test test”.

You can look at the URL-encoded values at the following link http://www.i-technica.com/whitestuff/urlencodechart.html

Special Characters

XML has a special set of characters that cannot be used in normal XML strings.

These characters are:
& - &amp;
< - &lt;
> - &gt;
" - &quot;
' - &#39;

For example, the following XML string is invalid:
<SMS_SEND to="MSISDN" uid="UNIQUE UID" reply="EMAIL:email@address.com" to_name="">This & That</SMS_SEND>

Whereas the following is valid XML:
<SMS_SEND to="MSISDN" uid="UNIQUE UID" reply="EMAIL:email@address.com" to_name="">This &amp; That</SMS_SEND>

Note that we have replaced '&' with '&amp;' in the second XML string which makes it valid.
These special characters must be replaced before any URL Encoding is done.

Batch Sms Sends

Although it is possible to do large bulk sends, it is not recommended. Large XML files could take a while to submit to the server and this might lead to a timeout. Should an error occur during a large bulk send it also becomes harder to determine exactly which messages succeeded and which ones failed. For bulk sends, it is recommended that either each message is submitted on its own, or that the bulk send be broken up into submissions of 25 messages at a time. This will allow for quicker submission to the server and also makes it easy to resume sending should an error occur.

Sockets and Timeouts

When sending on a socket the behaviour of the server is as follows:

  1. Receive data (buffer)
  2. Validate XML
  3. Parse XML
  4. Persist SMSs into the database.
  5. Generate response

The time you may have to wait for after sending, before receiving a response back from the server can be quite long. The server processes between 2500 – 3200 SMSs per minute. Therefore a delay of between 1.5 and 2 minutes can be expected on a send of 5000. As a result we ask that batches be broken up into sizes of less than 5000 at a time. This will increase the availability of the server.

Testing

XML can be tested by posting it to the following URL: http://sg1.channelmobile.co.za/sms/test

XML posted to this URL will not cause any smses to be created. The XML is merely parsed and any errors are returned in the same way as they would be with and actual message send.