Vidensdatabase

HTTP API for Bulk SMS

This document provides the guidelines on how to use the HTTP SMS API interface for sending a single SMS or bulk SMS to valid Mobile phone numbers.

You submit all your requests over HTTP in the host {base_url} : http://push.globalsms.ae

The parameters used for sending the SMS messages are described in the following:

• Username: {username} represents the Client username account.
• Password: {password} created on the Client password account.
• Destination: {destinationnumber} is the valid mobile number where the SMS is to be sent.
• Source: {senderID} is the Sender ID of the sent message.
• Text/content: {messagecontent} is the body of the message.
• Data coding: {DataCodingNumber} defines the encoding format:

SMS Gateway protocols tend to support more character encodings than just GSM 03.38. But, the bad news is that very few of these encodings actually matter. It depends on the carrier network of the handset, but most phones (especially internationally) will receive messages in either GSM or UCS-2 character encoding. This means that even though, for example, SMPP 3.4 supports character encodings like ISO 8859-1, ISO 8859-8, ISO 8859-5, IA5, and a mysterious unspecified Pictogram encoding, the message is probably going to get converted into GSM 03.38 anyway, so any characters in these encodings that are missing in GSM will be lost in the conversion.

Thus, for any message that cannot be encoded in GSM, the most reliable option is to encode it using UCS-2. UCS-2 is a now defunct character encoding that has since been replaced by UTF-16. These differences turn out not to matter in practice, because due to the lack of support for the UCS-2 encoding, in modern programming languages smartphones tend to just decode UCS-2 messages as UTF-16 Big Endian. This is good news, because it means in practice we can send non-BMP characters, such as Emoji characters, over SMS, despite the fact that the spec doesn't strictly allow it.

The drawback of UTF-16 messages is that since each character is 2 or 4 bytes, we can have a maximum of 70 fit into a 140 byte SMS message. (This is even true if only one character isn't in GSM, since the encoding applies to every character in the message). Note that if we're only sending Emoji or other non-BMP characters, then the limitation is actually 35. This is ignoring combining characters (e.g. diacritic marks), which could bring the count down further, depending on how you count the length of your text.

Supported Data Encodings

• Default GSM 7 = 0
  • https://en.wikipedia.org/wiki/GSM_03.38#GSM_7-bit_default_alphabet_and_extension_table_of_3GPP_TS_23.038_.2F_GSM_03.38
  • GSM-7 is a character encoding standard which packs the most commonly used letters and symbols in many languages into 7 bits each for usage on GSM networks.  As SMS messages are transmitted 140 8-bit octets at a time, GSM-7 encoded SMS messages can carry up to 160 characters.
  • GSM-7 is the standard alphabet for SMS messages, written up in the standard GSM 03.38. It is always supported on GSM In languages with more than 128 commonly used symbols, GSM-7 is mandated. However, local language support is implemented with shift tables or by changing text encoding to (16-bit) UCS-2 encoding.
  • The basic character set for GSM-7 can be found here.
  • For some characters, such as '{' and ']', an escape code is required - so even in a GSM-7 encoded message these characters will be encoded using two characters.
  • SMS messages contain 140 8-bit octets, so up to 160 GSM-7 characters may be transmitted: (140*8)/7 = 160.
• Unicode UCS2 / GSM 8 = 8
  • https://en.wikipedia.org/wiki/GSM_03.38#UCS-2_Encoding
  • Supported Launguages : Turkish, Spanish, Portuguese, Bengali, Gujarati, Hindi, Kannada, Malayalam, Oriya, Punjabi, Tamil, Telugu, Urdu, French, Greek, Russian, Bulgarian, Arabic, Hebrew and most Central European languages
  • UCS-2 is a character encoding standard in which characters are represented by a fixed-length 16 bits (2 bytes).  It is used as a fallback on many GSM networks when a message cannot be encoded using GSM-7or when a language requires more than 128 characters to be rendered.
  • UCS-2 and the other UCS standards are defined by the International Organization for Standardization (ISO) in ISO 10646. UCS-2 represents a possible maximum of 65,536 characters, or in hexadecimalsfrom 0000h - FFFFh (2 bytes). The characters in UCS-2 are synchronized to the Basic Multilingual Plane in Unicode.
  • Characteris an overloaded term, so it is actually more correct to refer to code points. Code points allow abstraction from the character term and are the atomic unit of storage of information in an encoding.
  • UCS-2 is a fixed-width encoding; each encoded code point will take exactly 2 bytes. As a SMS message is transmitted in 140 octets, a message which is encoded in UCS-2 has a maximum of 70 characters (really, code points): (140*8) / (2*8) = 70.
• Other Supported Encodings
  • ISO-88592 Eastern European Latin2= 1
    • https://en.wikipedia.org/wiki/ISO/IEC_8859-2
  • ISO-88591 Western European Latin1 = 3
    • https://en.wikipedia.org/wiki/ISO/IEC_8859-1
  • ISO-88594 North European Latin4 = 4
    • https://en.wikipedia.org/wiki/ISO/IEC_8859-4
  • ISO-2022 Japanese = 5
    • https://en.wikipedia.org/wiki/ISO/IEC_2022
  • ISO-88595 Cyrillic = 6
    • https://en.wikipedia.org/wiki/ISO/IEC_8859-5
  • ISO-88598 Hebrew = 7
    • https://en.wikipedia.org/wiki/ISO/IEC_8859-8

The parameters used for receiving DLRs are described in the following:

• Username: represents the username of Monty Mobile account at vendor side
• Password: represents the password of Monty Mobile account at vendor side.
• Sender: is the Sender ID of the submitting message
• Destination: is the Sender ID of the sent message
• MessageID: to be used in case if any enquiry about the message
• Delivery Status: the code of the delivery status
• Description: description of the delivery status
• Datereceived: the received date of the message
• Date coding: defines the encoding format of the message

For sending SMS messages, the user has the ability to request an authenticated HTTP(s) request with an appropriate HTTP method (Get and Post).

HTTP(s) Get Request for Single SMS

A single SMS is sent via the below URL by filling the correspondent parameters:

http://{base_url}/HTTP/api/Client/SendSMS?username={username}&password={password}&destination={destinationnumber}&source={senderID}&text={messagecontent}&dataCoding={DataCodingNumber}

Multiple Messages are sent via the below URL by filling the correspondent parameters:

http://{base_url}/HTTP/api/Client/SendSMS?username={username}&password={password}&destination={destinationnumber1},{destinationnumber2},{destinationnumber3}&source={senderID}&text={messagecontent}&dataCoding={DataCodingNumber}

A maximum of 500 numbers can be added in one destination string, with the number of length<=15

HTTP(s) Post Request for Single or Multiple SMS

The single or multiple messages are submitted by HTTP(s) post request via the

The messages are submitted by HTTP(s) post request via the following URI:  

http://{base_url}/HTTP/api/Client/SendSMS

The HTTP Header request is written in Json format and contains the following:

• Username
• Password
• Content-Type = application/JSON

The HTTP Body request is written in Json format and contains the following:

• destination
• source
• text
• datacoding

Example of HTTP(s) post request:

The Body is written as JSON language and contains the below parameters for sending a single or multiple SMS messages. A maximum of 500 numbers can be added in one destination string, with the number of length<=15

After submitting the request as per any of the above methods, you will get a response containing the following parameters:

• {ErrorCode}: State of the message (Values are shown below)
• {ErrorDescription}: Status of the message (Values are shown below)
• {Id}: MessageId to be used in case if any enquiry about the message
• {OriginatingAddress}: Alphanumeric source of the Message(Sender ID)
• {DestinationAddress}: Mobile Destination Number
• {MessageCount}: The number of concatenated messages, length could vary depending if text is Unicode or ASCII
• {MessageParts}: The number of each part for each message

 The Error Codes values and descriptions are:

 N.B: In case you are sending multiple messages, you shall receive multiple ids separated by comma.

HTTP Response Example:

Message Length

Messages containing any GSM7 characters are limited to 160 characters per SMS. When you send a SMS message over 160 characters the message will be split. Large messages are segmented into 153 character segements and sent individually then rebuilt by the recipients device. For example, a 161 character message will be sent as two messages, one with 153 characters and the second with 8 characters.

Certain characters in GSM 03.38 require an escape character. This means they take 2 characters (14 bits) to encode. These characters include: |  ^  {  }  €  [  ]  ~   and \  . In short, an SMS of all escape characters can only have 80 characters, instead of 160. Perhaps more devastating is that a message that was truncated at exactly 160 won't fit into a single SMS if it has a single one of these characters.

If you include non-GSM characters like eastern characters in SMS messages, those messages have to be sent via UCS-2 encoding. Messages containing any UCS-2 characters are limited to 70 characters per SMS and will be concatenated into 67 character message segments, even if the messages contain less than 160 characters.

Fixing the API

Once we knew what was possible, it was clear our API had some limitations, so it was time to start correcting these issues. Most of the bugs fell into just a few categories. To avoid our mistakes, the following concepts are important to keep in mind:

• Make sure your language or framework is interpreting percent encoded HTTP parameters as UTF-8 and not Latin-1.
• Make sure your database connection is set to UTF-8.
• If you're on MySQL 5.5 or better, make sure your UTF-8 columns are of type utf8mb4 and not utf8. The latter does not have support for non-BMP characters as it has a maximum of 3 bytes per character.
• If you're on MySQL 5.1 and you can't upgrade, you're going to need to find your own solution for non-BMP characters. Some options include: using a BLOB type and handling encoding/decoding yourself or escaping non-BMP characters (whatever scheme you come up with must be sure to produce valid UTF-8).
• In general, do not confuse "strings" and "bytes." If you have a collection of bytes, you must know the encoding in order to understand it as a string of text.

For checking the accounts Credit Balance, the user has the ability to request an authenticated HTTP(s) request with an appropriate HTTP method (Get Only).

The parameters used for sending messages are described in the following:

• Username: represents the Global SMS username account.
• WebLoginPasssword: represents the Global SMS web portal password.

https://access.globalsms.ae/OnlineApi/api/Billing?username={username}&password={WebLoginPassword}&isEnterprise=false

After you have sent a couple of messages, you are able to check if they were successfully delivered by providing an HTTP URL in order to push the DLR into it.

The request body is in JSON Format, and you have the ability to add, edit or delete the parameters (Name, value and description).

The below is an example of the parameter’s names with its Values & Description:

• MobileNumber: Mobile Phone Number
• SendDate: the date of sending message
• Receive Date: the date of receiving message.
  • StatusId: The status id of the message
    • 2
    • 3
    • 4
    • 5
    • 6
    • 7
    • 8
• Status: Message status
  • 2 = Delivered
  • 3 = Expired
  • 4 = Deleted
  • 5 = Undelivered
  • 6 = Accepted
  • 7= Invalid
  • 8= Rejected
• Message Id: to be used in case if any enquiry about the message
• Username: username of Monty Mobile Account
• Password: password of Monty Mobile Account

HTTP GET DRL API example:

http://{base_url}/GetDLR?MobileNo=$NUMBER$&Senddate=$SENDDATE$&ReceiveDate=$RECEIVEDATE$&Status=$STATUS$&MessageId=$MessageId$&StatusId=$StatusId$&Username=$Username$&Password=$Password$

 HTTP POST Request JSON Body:

HTTP Response Example:

des: Ba

JSON

 XML

cURL

PHP

Java

Ruby

C#

Python

 JavaScript

VB.net

C#

PHP