This document describes the M800 SMS Short Message Peer-to-Peer Protocol (SMPP) API for the purpose of integrating SMS into your applications and web systems.
The SMPP protocol is an open, industry standard protocol designed to provide a flexible data communications interface for exchanging SMS messages between a Message Center, such as a Short Message Service Centre (SMSC) and a Short Message Service Proxy (SMSP).
Using the SMPP protocol, an External Short Messaging Entity (ESME), such as a promotional marketing tool, may initiate an application layer connection with an SMSP over a TCP/IP network connection in order to send and receive short messages.
The M800 SMPP API supports a full feature set of messaging functions that allow you to:
• Transmit messages from an ESME to a single destination via the SMSC
• Define the data coding type of the short message
|The term SMSP will be used throughout this document to describe any SMPP "server" to which an SMPP "client," known as the ESME, can be connected.|
Once you have chosen your username and password, you will receive a confirmation email. Click the Active Now button in the email to complete the process of validating and setting up your M800 account.
Log in with your username and password (the page defaults to the M800 Dashboard).
You must purchase an SMS plan before you can get your system ID and password.
A sender number is the number that displays when you send an SMS message. You can add up to five sender numbers to your SMS-enabled M800 account.
You must purchase an SMS plan before you can add a sender number.
You must have at least one verified sender number before using the SMS SMPP API to send messages.
The M800 SMS interface supports the industry standard SMPP V3.3 and V3.4 protocols. Currently, our SMPP server only supports a subset of the SMPP specifications for V3.3 and V3.4, including messages sent from the ESME (transmitter and transceiver) to the SMSC.
For non-supported SMPP functions or commands, the M800 SMSP will reject the command/request with the corresponding ESME error code.
The submit_sm SMPP commands include mandatory and optional parameters. For mandatory parameters, SMSC will ignore any invalid value/non-supported parameters and reset to the SMSC default value and then deliver the message.
This is the sender number, which must be in international address format, starting with the country code. The sender number cannot contain any leading "+" or "00."
The sender number must be verified. Otherwise, the submit_sm request will be rejected.
The destination address must be in international format, starting with the country code, and it shall not contain any leading "+" or "00."
GSM Protocol ID (See GSM 03.40  220.127.116.11)
GSM Data-Coding-Scheme ( See GSM 03.40  18.104.22.168)
Length of the message text in bytes.
Up to 140 octets of data. This is the text that is transmitted to the mobile station.
SMSC has REJECT, FILTER, and PASS-ON options for each optional parameter:
FILTER – reset the value set to the SMSC default value and process the delivery
The following table includes a list of optional parameters that we support and their hexadecimally-coded tag fields (without descriptions).
Invalid Command ID
Invalid Priority Flag
Invalid Registered Delivery Flag
Invalid Sender Number
Invalid Dest Addr
Message Queue Full
Invalid esm_class field data
submit_sm or submit_multi failed
Invalid Sender Number TON
Invalid Sender Number NPI
Invalid Destination address TON
Invalid Destination address NPI
Invalid replace_if_present flag (Replace_if_present in submit_sm)
Invalid number of messages
Throttling error (ESME has exceeded allowed message limits)
Invalid Scheduled Delivery Time
Invalid message validity period (Expiry time)
Predefined Message Invalid or Not Found
ESME Receiver Temporary App Error Code
ESME Receiver Permanent App Error Code
ESME Receiver Reject Message Error Code
Error in the optional part of the PDU Body.
Optional Parameter not allowed
Invalid Parameter Length.
Expected Optional Parameter missing
Invalid Optional Parameter Value
Black listed number
Fail to pass individual (per SMSC binding) black list
Black listed number
Fail to pass Global SMSC black list
|Charging error due to low balance||0x00000400||Error while charging due to low balance|
As defined by the GSM 03.40 or 3GPP TS 23.040 specification, concatenation is provided by use of a User Data Header (UDH) in each message (submit_sm). A UDH contains and sets the following items:
In order to enable long messages, the UDH must be set in the SMPP parameter esm_class, and special user date header information must be present in front of the user data.
Following are two examples of UDH in two messages:
UDH SM 1: UDHL=05 IEI(1)=00 IEIDL(1)=03 IED(1)=64 IED(1)=02 IED(1)=01 DATA SM 1 : <text part 1-2> UDH SM 2 : UDHL=05 IEI(1)=00 IEIDL(1)=03 IED(1)=64 IED(1)=02 IED(1)=02 DATA SM 1 : <text part 2-2>
The SMPP protocol provides the following optional parameters to enable concatenation. Use of these SMPP parameters in a GSM environment results in the use of the UDHs, but the formatting is left to the SMSC and not to the ESME application, which makes it easier to use concatenation.
Sar Optional Parameters
Originator generated reference number allowing the parallel transmission of several segmented messages
The total number of fragments within the concatenated short message
The sequence number of a particular message within the concatenated short message
Establish a network connection for the ESME with the M800 SMSP, and then issue an SMPP Bind request to open an SMPP session.
• OPEN (Connected and Bind Pending)
An ESME has established a network connection to the SMSC but has not yet issued a Bind request.
Log in to the M800 Dashboard to view the access details.
Throughput : 5 sms / sec
Connections : 2 connections max (may be one TX and one RX, or two TRX)
A connected ESME has requested to bind as an ESME Transmitter (by issuing a bind_transmitter or bind_transceiver PDU) and has received a response from the SMSC authorizing its bind request. Your SMPP credentials can be found in the M800 Dashboard's API Setting when you log in to the M800 portal.
The correspondence with SMPP parameters are shown in the table below:
SMPP Dashboard Configuration
[password generated by M800]
33 or 34 (required for TRX)
SUBMIT_SM is used by an ESME to submit a short message to the SMSP for onward transmission to a specified subscriber. The submit_sm PDU does not support the transaction message mode.
An ESME application can send regular text by using the submit_sm request. When using the submit_sm operation, the message text data should be inserted in one of the following two fields:
Simultaneous use of both fields is not allowed.
When using the short_message field, the sm_length field indicates the length in octets of the short_message field data and must be set. If the message_payload field is used, the sm_length field must be used, as well, but it will be set to 0 to indicate the use of the message_payload field. Up to 254 octets can be inserted in the short_message field, while the message_payload field is able to contain up to 64K octets.
The GSM standard, however, defines a maximum of 140 octets for a single short message and therefore does not support the transmission of more than 140 octets per message. Therefore, a receiving SMSC will usually not accept a submit operation that results in a short message of >140 octets, unless it has implemented an automatic concatenation mechanism, which divides a long message into multiple parts of 140 octets.
Use the unbind operation to de-register an instance from the SMSP and inform the SMSC that the ESME no longer wants to use the network connection for the submission or delivery of messages. The unbind operation may be viewed as an SMSC log-off request to close the current SMPP session.
Connections that are kept open longer than the server-configured timeout (currently 40 +/- 5 seconds) without activity are automatically closed with an SMSP-initiated unbind operation. To shorten the connection establishment time, keep the connection persistent. For persistent connections, the ESME must maintain the active link ensuring traffic (eg. A heartbeat enquire_link) before this interval has expired.
Since the server cannot send an ENQUIRE_LINK request to the bound connections, we recommend that developers send the ENQUIRE_LINK request by either the ESME or SMSC in order to provide a confidence check of the communication path between the ESME and SMSC. Upon receipt of the request, the receiving party should respond with an enquire_link_resp, thus verifying that the application level connection between the SMSC and the ESME is functioning. The ESME may respond by sending any valid SMPP primitive.
When sending text from an ESME to the SMSC, the coding of the short message text inside the SMPP PDU field must be supported by the SMSC and defined in such a way that the SMSC is able to interpret it. When sending a short message from an SMSC to a mobile station, coding of the data determines what is possible at the ESME side. GSM has defined the following text data coding options:
The GSM default alphabet looks like the ASCII table (characters 0-127) with the difference that most of the control characters are not present and are replaced by characters from the LATIN-1 upper table (characters 128-255). The SMPP specification offers many coding options, but not every offered coding is by default implemented at the SMSC. The following options are usually implemented at the SMSC:
The M800 SMS interface supports the following message encoding: