Frequently Asked Questions

Why do you use non-standard ports like 5567, instead of the usual port 80?

We do this mainly to bypass proxies, especially transparent proxies - your ISP will often have a transparent proxy intercepting traffic on port 80, which you may be unaware of. Such proxies can cause various anomalies, like poor throughput/outages, DNS resolving problems, and even duplicate submissions. Additionally we can offer better performance ourselves via direct access to, say, port 5567.

You can fall back to port 80 if you have firewall-related problems connecting to us (but we recommend that you rather take the time to allow outgoing access to ports 5567 and 7512 via your firewall). To do so, simple remove :5567 (or similar) from the URL.

Why should I use HTTP POST instead of HTTP GET?

Please never use GET in production systems. We allow this method purely for very simplified testing of our APIs. If you use GET, you may find that some characters are not supported, messages may go missing, or entire requests may fail, despite your initial tests showing no such problems.

NB: Do not use POST to a URL that contains a query string (e.g. ?username=john). Only POST to a URL with no query string, thus ensuring that your query string is sent in the body of the HTTP request. Failing to do so will result in the same problems as using GET.

HTTP POST requests have a notion of a request length, as well as a character encoding, both of which GET lacks.

GET requests have no inherent/agreed/default character encoding according to any standard, and there is no way for the HTTP request to specify the underlying encoding of the query string. The character encoding is therefore server-specific. The character encoding for GET requests to our server is intentionally unspecified, with no claim made that the encoding currently in use will remain in use in future.

In a GET request, the query parameters are sent in the HTTP headers, for which there is no way to specify the length. As such, various systems will apply arbitrary length limits to the query string, which often results in the truncation of long query strings. In our context, this may exhibit as some recipients seeming to disappear during message submissions.

How do I send Unicode (16-bit) SMSs?

This sends the letters BCD in Unicode:

«EAPI URL»/submission/send_sms/2/2.0?username=john&password=xxxxxxxxx&dca=16bit&msisdn=441231234&message=004200430044

0042 is in hexadecimal, which is 66 in decimal, and corresponds to ASCII 66, or B. Do not leave out the zeros from this example. This example should display correctly on almost every phone, but will appear no different to you than just sending BCD as a normal SMS.

Here’s an example with some Arabic characters: 0600060106020603060C. Don’t expect it to display correctly unless your phone supports Arabic characters (which is only likely if you are in an Arabic-speaking country).

You will find Unicode charts (which map characters to codes) at www.unicode.org/charts.

How do I send ringtones/logos etc?

If you need to find out how to encode smart messages (ringtones, operator logos, picture messages, etc) for Nokias, the best place to look is at www.forum.nokia.com. You can create an account for free. Log in and go to Developer Home: Resources: Technologies: Messaging: Short Messaging: Support / FAQs: Smart Messaging FAQ. This is the best resource we know of.

Similarly, under Short Messaging: Documents, look for Smart Messaging Specification, Revision 3.0.0, which also has some useful examples.

For free (non-commercial) software to do encoding for you, have a look at Mike Kohn’s Ringtone Tools - a great set of very useful utilities for ringtones, logos, etc with support for multiple cell manufacturers’ products. Note: SCKL headers are not used in 8-bit mode, so we recommend using, for ringtones for example, ringtonetools -u -s 280. Your resultant 8-bit messages should have up to 280 characters (or more correctly put, up to 140 octets, where FF is an octet, and not 140 characters as the Ringtone Tools software implies. Thereafter (if you need to support concatenated messages), we recommend that you vary the message id in the headers for each set of messages produced. So, if your output from ringtonetools was 0B0504158100000003010201..., you could cycle the message id of 01, in the range from 00 to FF. Therefore, your next pair of messages’ headers could be:
0B0504158100000003020201...
0B0504158100000003020202...
where the id 01 has been cycled to 02. This will prevent your multiple messages from the same source number to the same mobile causing problems (through delayed or non-delivery of the concatenated parts for instance, and/or multiple submissions to the same mobile over a short period).

How do I send a WAP push service indication?

For a simple WAP push, your UDH and WSP headers are as follows:

UDH

06
05
04
0B84 destination port
23F0 origin port

WSP headers

DC Transaction ID (used to associate PDUs)
06 PDU type (push PDU)
01 HeadersLen (total of content-type and headers, i.e. zero headers)
AE Content Type: application/vnd.wap.sic
Suppose you wanted to send this as your WAP push
URL: http://192.168.0.1/blah
message displayed: push
You will have to change your XML:
>si<

<indication href="http://192.168.0.1/blah">
push
</indication>
</si>

into a WBXML
WBXML is a binary representation of an XML document. The specification is here, but you should rather look at a library to do the encoding for you, e.g. libwbxml - a C library for creation and decoding WBXML, plus command-line programs. An encoder will allow you to automatically generate the WBXML from XML

This in turn, the WBXML binary representation, needs to be converted to Hex values to complete the WAP push. Please have a look at the a simple perl script here

For this simple example, you’ll end up with this HEX representation of the original XML:
02056A0045C60C033139322e3136382e302e312f626c616800010370757368000101

Adding the headers as outlined above the complete string is as follows:
0605040B8423F0DC0601AE02056A0045C60C033139322e3136382e302e312f626c616800010370757368000101

Here’s a complete breakdown of the message:

WBXML section

02 WBXML version 1.2
05 SI 1.0 Public Identifier
6A charset=utf-8
00 string table length == 0

45 service indication, with content
C6 >indication

0C href=”http://
03 string to follow
3139322e3136382e302e312f626c6168 (192.168.0.1/blah)
00 string termination

01 > (close of >indication< tag)

03 string to follow
70757368 (the title “push”)
00 string termination

01 >/indication<
01 >/si<
You will find the OMA Wireless Session Protocol Specification and WAP Service Indication Specification here.

Note that the example above excludes an si-id, in which case the si-id defaults to the href parameter. A mobile will typically overwrite an already-stored message which exists with the same si-id (which in this case above means the same href, effectively). At the same time, it will typically notify the user that a new push was received, but be aware that some handsets might not do so.

Please try to google the Smart Messaging forums on more detailed information on Provisioning.

How do I send a vCard?

Presuming your vCard can fit within a single SMS, here’s an example:

06050423F40000424547494e3a56434152440d0a56455253494f4e3a322e3
10d0a4e3a446f653b4a6f686e0d0a54454c3b505245463a2b343431323331
3233340d0a454e443a56434152440d0a

Breakdown:

06050423F40000: Standard User Data Header (port 23F4) for a vCard.

The rest of the hex above is simply the following text (as per the vCard specification), encoded to hexadecimal octets:

BEGIN:VCARD\r\n
VERSION:2.1\r\n
N:Doe;John\r\n
TEL;PREF:+441231234\r\n
END:VCARD\r\n

(note the termination of each line with a carriage return-newline pair).

Compatibility: vCards should work on most Nokias. We’re not sure about other makes. However, vCards are not based on a proprietary (or even a Nokia-specific) specification.

How do I send a vCalendar entry?

These can be implemented similar to vCards (see above). However, you will almost certainly need to send at least two concatenated messages for a typical VCalendar entry.
See the Nokia Smart Messaging FAQ (at www.forum.nokia.com) for examples.