As we were re-writing it we took the chance to make a few other changes too, don’t worry though, if you’re already using the API we haven’t changed anything, all the old URLs and parameters will still work.

Url Changes

From now on all API addresses are on api.mediaburst.co.uk rather than sms.message-platform.com, we feel it makes more sense as you can instantly tell it’s the mediaburst API.

All examples now use SSL for added security, you’re still able to turn it off though.
We have no plans to disable the old sms.message-platform.com.

So the URL for sending through our simple HTTP API becomes https://api.mediaburst.co.uk/http/send.aspx

Delivery Receipts

We’ve renamed a few of the merge parameters for consistency, when you send a text message you use the To parameter for the mobile number, and now the delivery receipt will too. Don’t worry though all the old names still work.

Simple HTTP API

We’ve clarified which features are available through the HTTP API. If you want advanced features they’re all available through the XML interface.

Our new simple parameter list now consists of:

• Username
• Password
• To
• Content
• From (Optional – Message originator)
• Long (Optional – Allow up to 459 characters)

Email to SMS address changes

Again to tidy things up, we’ve changed all email to SMS email addresses to use mediaburst.co.uk rather than message-platform.com.

The new addresses are:

It certainly indicates we need more information on the website about our international credentials, but while we prepare something here’s a taster:

Basically sending internationally is as easy as sending to UK destinations, you just need the international prefix (e.g. 44) on the mobile phone number. Line your messages up and watch them deliver round the world. They’ll be just as happy zipping down the road and to the next city too.

Get the code

There’s plenty of useful stuff in our SMS API code kits that will help you with integrating. There’s C#, PHP, Perl, ASP plus a Ruby Gem if that’s your thing.

If you need expert help, we’ve got that too. Our techies have years of experience.  They’re also the guys watching your back and maintaining our platform 24/7.

A couple of tips for you

1. Some international networks block alpha originators or company names.  Use the ‘from’ field parameter to set a numeric originator when sending outside the UK.
2. Just use the international country code. There’s no need for the ’00′ or ‘+’ with our SMS API

Any questions, just let us know, always here to help.

How does it work?

We simply maintain an access database against your account and block anything outside of your named range. It might not be the most exciting thing, but it could be crucial.

For an added level of security, you can also set your system to allow our named range of IP’s for the mediaburst SMS API, which are as follows:

CIDR                                      Netmask                              Address Range

89.248.48.192/27              255.255.255.224                89.248.48.192 – 89.248.48.223

217.20.43.96/27                255.255.255.224                217.20.43.96 – 217.20.43.127

How do I lock it down?

Just send us an email to hello@mediaburst.co.uk with your account details and your named IP ranges and we’ll do the rest.

All messages regardless of coming through the SMS API, from Textburst, or Outlook Mobile Service will be dealt with in this manner. You don’t need to change a thing.

This is a big step forward in deliverability to the USA. The shortcode 43704 is fully registered with the Common Short Code Administration so complies fully with their network and regulatory requirements.

North America has some unique complexities in their SMS industry that mean delivery to mobile numbers in the USA can be problematic. Before this upgrade we could deliver SMS to the USA but had to disclaim the service, which, I admit didn’t feel comfortable.

In addition to our discomfort we are also receiving a greater demand for messaging to the USA, and, have a product in the pipeline that will squarely align our services with a large body of software developers in the USA.

The general problem was messages were classed as arriving from an international destination meaning a recipient of the message could be charged (some pay for SMS received in the USA) the rate of an international SMS.

Not only that but all machine to handset orientated messages in the USA should come from a numerical number (rather than an alpha numeric that we use in Europe) so that the recipient could reply to opt out of receiving further communication.

All our SMS to the USA came from a numerical long number but that wasn’t actually a proper reply path for opt outs.

With this upgrade we are now in the fortunate position of delivering on a dedicated and registered short code, we deliver via a fully registered carrier based in the USA, and can process the opt outs as is the requirement.

A big step forward indeed, if you have any questions at all about SMS delivery to America then get in touch.

We do provide some excellent Delivery Status information in our Online SMS service textburst and even more if you send via our SMS API. By understanding and using this data you can cut down on undelivered messages and make some good cost savings too.

SMS API

Users of the API can get some pretty detailed information on the delivery status of each message, the full table is in our SMS API documentation.

They 2 key parameters to be concerned with are DELIVERY_STATUS and ERR_CODE.

If under DELIVERY_STATUS you receive UNDELIV or REJECTED (undelivered or rejected) then it warrants further investigation using the ERR_CODE parameter.

ERR_CODE numbers 5 or 9 indicate no matter how many times you try you simply cannot send a text message to this number. Most likely because the number has been cancelled or less likely the phone does not support text messaging. If you get a 5 or 9 we suggest you remove this number and try other means of contact.

ERR_CODE numbers 4, 6, 7, or 10 indicate a Temporary error and chances are it’ll clear given time. We suggest you hold off sending to this number for a week or so, maybe they are on holiday or having technical difficulties with their phone.

It’s also likely you’ll see some of the less decisive error codes including the unhelpful network error code of “unknown – no details provided by the network”.

By doing a periodic review of all your undelivered or rejected messages you can help reduce these errors. Look for the number of occurrences you tried to send to any one given number, if it’s always failing for whatever reason then chances are this is no longer a valid contact number for your customer.

Textburst

If you’re using textburst then the error code information is summarised and we suggest a periodic review of the information to identify bad data. Warning: you might need someone handy with a spreadsheet.

Once you have logged into textburst go to Sent Messages.

Click the small pie chart next to each batch of sent messages.

Then select “List View” in the main heading.

You’ve now got a list of each message, the mobile number and delivery status. You’ll notice on the right hand side an option to download the complete information to a spreadsheet.

We suggest downloading all your sends and searching for those numbers that regularly or never deliver, using this data you can either delete contacts or follow your own path to correct the data for future sends.

I hope this is helpful, if you need any more information or guidance then just ask.

What’s in this release?

This milestone release doesn’t contain any major new features for you, our users, it’s all about making our lives easier at mediaburst and allowing for future changes.

We’ve changed to .NET 4

Microsoft released version 4 of their .NET framework a couple of months ago, along with it came Visual Studio 2010. Although there are no groundbreaking changes in this new Visual Studio it solves various day to day niggles.

Code rewriting

We’ve re-written some internal code that passes messages around between systems. It’s just housekeeping really, making use of the improvements between versions 2 and 4 of the .NET framework. The biggest change is the switch from ArrayLists of messages to strongly typed Lists using the new support of covariance and contravariance in generic types. This change allows the compiler to check what we’re adding to the list at compile time, rather than run time, hopefully avoiding any mistakes.

No more image messages

We’ve removed support for Nokia and EMS image messages. They’re small black and white bitmaps which look awful on modern phones, a much better choice, with wider handset support, is MMS. Processing these took large chunks of bespoke code, without them our sending scripts are so much easier to maintain as there’s only one set of logic.

Updated logging

And finally we’ve tweaked our sent message logging to make a number of internal reports run off a single database table. We currently have to link two databases on different servers if we want the same level of detail.

For sending messages, our SMS API will automatically take care of the settings need to do this as long as the ‘Concat’ parameter is set when sending the message. The Concat parameter can take the value of 1, 2 or 3, and indicates how many SMS you are willing to use to attempt to send a message.

However, if you have messages which are sent from phones to your application (MO Messages), an understanding of how concatenation works can be useful if users are likely to send messages over 160 characters.

User Data Header (UDH)

The SMS that make up a concatenated SMS are related together by using the User Data Header (UDH) of an SMS. The UDH is a collection of bytes which can be put at the start of the SMS content. It can be used to control what happens to the rest of the content. For instance, it was used to send the older style of Nokia picture messages.

To indicate that the content contains a UDH, a flag on the SMS called the UDH Indicator (UDHI) must be turned on. This tells the phone that it must separate the UDH from the rest of the content.

Format of an SMS with a UDH

The phone separates the UDH by reading the first byte of the content. The number in this byte is the length of the rest of UDH and is called the User Data Header Length (UDHL). The phone then knows how many bytes make up the UDH and can separate it from the rest of the message.

As already stated, a UDH can control various things and so can contain various commands. These commands are called Information Elements (IE’s). These IE’s always take the following format: an Identity Element Identifier (IEI) followed by the Length of the IE Data (IEDL) followed by the IE Data (IED). A UDH can contain 1 or more of these IE’s.

UDH’s for Concatenated SMS

For concatenated messages the IE’s that we are interested in are the ones with Identifiers (IEI) of 00 or 08. These indicate that the rest of the message is a concatenated message.

Let’s take an example of using the 00 Information Element Identifier.

The 00 IEI always has an IEDL of 03. That is, there are 3 bytes in the IE Data section.

The first byte is a reference number. This reference number must be the same for all SMS that make up a particular concatenated message.

The second byte is the total number of SMS that go to make up the concatenated message.

The third byte is the part number that this particular SMS is.

So if we have a message that is split across two SMS the bytes in the SMS may be:

First SMS: 05 00 03 A6 02 01 .. bytes that make up the first part text ..
Second SMS: 05 00 03 A6 02 02 .. bytes that make up the second part text ..

The 08 identifier works the same way as the 00, but instead of a 1 byte reference number, it uses a 2 byte (16 bit) reference number. Therefore its IEDL is 04, there are 4 bytes in the IE Data section. These are as follows:

The first and second bytes make up the 16-bit reference number.

The third byte is the total number of SMS that go to make up the concatenated message.

The forth byte is the part number that this particular SMS is.

So another two SMS examples could be:

First SMS: 06 08 04 F4 2E 02 01 .. bytes that make up the first part text ..
Second SMS: 06 08 04 F4 2E 02 02 .. bytes that make up the second part text ..

The API

As mentioned at the start of this article, our API will take care of all of this for sending messages. All you do is set the ‘Concat’ field to maximum SMS that you are willing to use to send a message.

For receiving messages, our API will forward through the individual SMS that make up a concatenated message. The UDH is already removed from the content and is present in the UDH parameter as the hex encoded bytes. The rest of the content is placed into the Payload parameter.

For most single SMS, a UDH parameter will not be present and so the parameter will be blank. But for concatenated SMS, the receiving script can check the UDH for the 00 or 08 IEI’s to allow it to piece together the original message.

Gone are the days of huge pdf files and big print runs. The Online version is well structured so you can easily find the sections you need. If you need something specific then there is also a handy search facility.

To make life easy there is a large bank of example code covering all the different integration protocols.

Additionally, the online guide covers both SMS and MMS.

The UK mobile networks all use the GSM standard, and as such, a standard text message is limited to the GSM character set.

An SMS can contain up to 140 bytes. The GSM character set is encoded using 7-bits, rather than the usual 8-bits that make a byte. This means there can be 160 characters in an SMS.

This 7-bit limitation means only 128 standard characters can be encoded. The GSM standard gets round this by also having the Extended GSM character set. These are another 10 characters which are actually sent by sending two 7-bit characters, an escape (ESC) character followed by another character. This means that 160 ‘£’ symbols can fit in a single SMS, but only 80 ‘{‘ symbols.

If you need to send other characters than those in the GSM character set, then take a look at UCS-2 messaging which allows sending most unicode characters, but as each of these takes 2 bytes it means only 70 characters can be sent per SMS.

So our customers don’t need to bother converting characters into the GSM encoding or escaping the extended characters, our SMS API accepts messages in UTF-8 encoding.

Update: Since posting this we’ve released an article on how to do GSM character encoding in .NET

The tables below show a full list of the GSM characters, standard and extended. They also show the equivalent UTF-8 encoding need to send into our API.

Standard GSM Characters

Extended GSM Characters

In an SMS these are prefixed with the escape character (1B) and therefore take up 2 of the 160 characters of an SMS. They do not need escaping when sending into our API.

When a message delivery fails and the network returns extra information to us regarding the failure, we can now send this information back to you in a standardised way.

The error code parameter is already defined in section 3.5 of the our API. Please contact us if you want this enabling on your default delivery receipt script. Alternatively, if you set this information when you send a message, you just need to use the ERR_CODE parameter. For instance, if delivery receipts are currently set up to be a GET request using the following parameters:

client_id=#CLIENT_ID#&status=#DELIVERY_STATUS#&msg_id=#MSG_ID#

Then the error code can be also passed by changing this to:

client_id=#CLIENT_ID#&status=#DELIVERY_STATUS#&msg_id=#MSG_ID#&err_code=#ERR_CODE#

By default, the encoding is set to UTF-8, but it also supports Latin-1, UCS2 (Unicode), or GSM encodings.

Give us a phone if you want to know more.