Skip to content



Mobile Terminated SMS, i.e. An SMS generated by an application going through a gateway to an a device. Often also referred to as Sent SMS and Outgoing SMS.


Mobile Originated SMS. An SMS sent by a device coming through a gateway to an application. Often also referred to as Incoming SMS and Received SMS.


Mobile Station International Subscriber Directory Number, but you may think of this as the full mobile number, including area code if available and the country code, but without prefixed zeros or +.


  • 4510203040 (typical Danish format: 10 20 30 40)
  • 46735551020 (typical Swedish format: 073-555 10 20)
  • 17325551020 (typical US format: (732) 555-1020)

The MSISDN is easily interchangeable with E.164 numbers, you simply remove or add the leading + in E.164. It can contain up to 15 digits, so we use an unsigned 64-bit integer.


The standard format for international phone numbers. Up to 15 digits.


Mobile Country Code, as defined by the ITU-T E.212 standard.


Mobile Network Code, as defined by the ITU-T E.212 standard.

GSM 03.38

The de facto standard encoding in SMS, which supports up to 160 normal characters in a single SMS, and 153 normal characters in each SMS in a chained/concatenated SMS. It achives this by using 7 bits for each character and supports the common characters in most western languages.

The full character set is:

  • Basic Latin
    • a b c d e f g h i j k l m n o p q r s t u v w x y z
    • A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
    • 0 1 2 3 4 5 6 7 8 9
    • ! " # $ % & ' ( ) * + , - . / _ : ; < = > ? @
  • Whitespace
    • Space   Newline \n and Carriage Return \r
  • Special Characters
    • £ ¥ § ¿
  • Greek Characters
    • Δ Φ Γ Λ Ω Π Ψ Σ Θ Ξ
  • Diacritics
    • è é ù ì ò Ç Ø ø Å å Æ æ ß É Ä Ö Ñ Ü ä ö ñ ü à ä ö ñ ü à
  • Extra Special Characters - using double width to be encoded with
    • ^ { } [ ] ~ |

Furthermore wikipedia has a good page which shows the encoding as a table.


Universal Coded Character Set, an early Unicode implementation. For the most part you can use UTF-16-BE (Big Endian) interchangeably with UCS-2. This encoding is used when sending messages that cannot be encoded in GSM 03.38, such as when using non-latin based languages or emojis.

UCS2 Lies

Unlike UTF-16, UCS2 is a fixed width encoding using 16 bits per code point. This limits the available code points to 216 or 65 536, which technically limits UCS2 encodings to the Unicode Basic Multilingual Plane.

The reason it is still possible to send emojis using UCS2 is that it is almost impossible to find a UCS2 codec in most modern programming languages - which powers most phones. Fortunately UTF16-BE is a superset of UCS2 with the unused code points near the end of the page assigned to surrogate pairs which allows the encoding to use multiple 16-bit code units per code point.

So everyone cheats and just uses UTF16-BE instead of implementing their own UCS2 codec.

This does mean that a SMS containing emoji (or other code points outside the BMP) is strictly speaking not quite encoded correctly using UCS2 when forwarded via SMPP, but every system in the chain of delivery either does not care about if the encoding is correct or just uses UTF-16BE.


Despite the somewhat unfamiliar name, the concepts backing webhooks should be familiar to most developers that have worked with web technologies. A webhook system is in its essence a user configurable system that allows events to be sent to from the system to a remote system accessible on a certain URL. Such an event could be a SMS status change that needs to be communicated from our systems to your systems, say for the sake of example that you have configured our webhook system to send events to, then on each event about SMSes that happen in our systems or that we receive from local operators, we send to that URL, with the event encoded as json.

All it requires from you is a webserver of sorts that is able to receive, process, and respond with a 2xx status code.


A simple and fairly common data format, derived from JavaScript.