Telia Lithuania Xml Api Emulation

Every request to the service must include authentication, i.e. username and password (or equivalent).

probably from an application

With the contents of the HTTP body:

A successful request will return 200 OK and a plain text result of the following format.

If multiple recipients were specified, the same five lines will result, but each of the result texts will appear for each destination, separated by commas:

If no message could be sent, either because all recipient numbers were invalid or due to syntax errors or missing data in the XML request, the result will have an appropriate HTTP error code (400 Invalid request or 401 Unauthorized are the most common) and a plain text error message describing the problem. For example, if a time in the past is given for the <timing> element, the result will be status code 400 and:

will output (if the timing date is in the future)

The character set used in the input to the API does not affect the resulting SMS. Instead, the characters that are requested to be sent will determine the size and pricing of the message.

Most network operators globally support all printable characters in SMS messages. They also support the sending of longer SMS messages by dividing the content into several SMS message parts (with some exceptions, like South Korea). An SMS message part is limited in size to 140 bytes; longer messages will require more parts. The character set used, not the language, will determine how many parts are needed. The pricing is based on the number of SMS message parts sent. Normally, the recipient’s mobile handset will automatically reassemble the parts of a divided message in the correct order, without any action needed by the recipient.

The GSM standard regulates SMS communication globally. While all characters are supported, some characters used in Western European languages are given special treatment. Two character encodings (character sets) are supported by almost all network operators in the world, and therefore by us: GSM-7 and UCS-2.

By GSM-7 we mean the internationally common GSM-7 alphabet according to GSM 03.38 / 3GPP 23.038 without any national language shift table (only the basic character extension). See for example https://en.wikipedia.org/wiki/GSM_03.38 for details.

The GSM-7 encoding uses 7 bits per character to encode only characters from these Western European languages (including numbers and some punctuation), while the UCS-2 encoding can encode characters from any Unicode alphabet and uses 16 bits per character. If every character in a message can be encoded with GSM-7, the message will employ the more compact GSM-7 encoding. If any character in a message cannot be encoded with GSM-7, UCS-2 will be used for the entire message.

Since the GSM-7 is a 7-bit character set, 160 characters will fit into one 140 bytes SMS part. The UCS-2 is a 16-bit character set and can accommodate only 70 characters in a 140 bytes SMS part. If a GSM-7 encoded message is longer than 160 characters, or a non-GSM-7 encoded message is longer than 70 characters, it will be divided into more than one part. Due to how such parts are constructed, multi-part SMS messages can only fit 153 GSM-7 characters or 67 UCS-2 characters per part. All parts of a message will use the same encoding, so they will all be GSM-7 or all UCS-2.

The inclusion, even accidentally, of a non-GSM-7 encodable character in a message will therefore transform it into a UCS-2 encoded message. This message will have a larger number of shorter parts, and the send-out will be more costly. Therefore, when sending SMS messages in Western European languages, it is often advisable to be on the lookout for any such characters that may be included in the message. For instance, some characters automatically generated in some circumstances by Microsoft Word, like curved citation marks (curved quotes) and unbreakable spaces, are not included in the GSM-7 character set. French vowels with the accent circonflexe also do not fit into GSM-7. Unsurprisingly, Cyrillic, Arabic, Chinese, Thai, Japanese and many other alphabets are not included, and neither are emojis, while ordinary text in English, Swedish, Finnish, German and similar languages will fit into the GSM-7 encoding. Lithuanian text is not included in the GSM-7 encoding, and will always use the UCS-2 encoding. No special effort is needed from the user to select the encoding. The Euro-sign (European Union currency symbol) is included in the GSM-7 basic character extension, which we support.

Operators around the world use widely varying status messages, especially for error conditions. When a delivery receipt (DR) arrives from an operator, we classify the status message into one of the following categories (status codes). We have done this for several years, and virtually all messages get classified into an appropriate status code category, because we recognize non-standard status message texts from hundreds of mobile operators.

The legacy XML API uses a smaller set of status messages, and the following translation table is applied to generate the appropriate values for the DR XML callback attributes, code, codeDescription and status.

The service will need no extra installation on top of the new system, except that load balancers, firewalls and/or proxies must be set up to forward incoming POST requests to https://smsapi.telia.lt/teltsms/sendxml which listens at the port associated with /teltsms in the ws application server process, and to allow outgoing callback POST http(s) requests to the customer’s supplied url.

The customers may use their old usernames and passwords from the legacy system, if these are provided to the new system administrators with one of the standard password hashing algorithms applied, and accounts with the corresponding credentials are set up. The account should at a minimum have the API role, for the service to work. The emulation is a layer on top of the new system, and does not keep any separate information on its own. The c_endpoint column in the sent_messages database table will say TELTSMS for these messages, but they otherwise look and feel and are processed as all other messages in the new system.

The callback urls for callback of delivery receipts (DR) and incoming messages (MO) should be set up on the customer’s account with the callback type TELTSMS and the urls probably starting with "https://". The service does currently not expect to authenticate itself with the customer url, but there are options for adding (static) authentication headers to the callbacks if a customer insists on that.

The emulated service is not expected to be updated or improved further, and customers are ultimately supposed to migrate to the newer APIs available, which will be regularly maintained and supported.