SMPP API
The following sections overview the basic concepts and characteristics of SMPP. The documentation section goes into greater detail and this is where you can find the full SMPP PICs, specifications and guidelines.
Protocol Version
Owner
Description
V5.0 2003
SMS Forum
This version is an enhancement of V3.4.
The specification incorporates many changes defined by the SMS Forum during the lifetime of V3.4. Th layout has also been revised to cater for a more detailed and clearer description of the protocol functionality.
V3.4 1999
SMS Forum
This version of SMPP is based on V3.3 and was intended to provide a fully backward compatible specification to V3.3.
V1.0 1991 – V3.3 1999
Aldiscon Ltd
The original specification.
In order to make use of the SMPP Protocol, a SMPP session must be established between the ESME and Message Centre or SMPP Routing Entity where appropriate. The established session is based on an application layer TCP/IP or X.25 connection between the ESME and MC/RE and is usually initiated by the ESME.
There are three forms of ESME-initiated session:
Transmitter (TX) – When authenticated as a transmitter, an ESME may submit short messages to the MC for onward delivery to Mobile Stations (MS). A transmitter session will also allow an ESME cancel, query or replace previously submitted messages. Messages sent in this manner are often called mobile terminated messages.
Receiver (RX) – A receiver session enables an ESME to receive messages from a MC. These messages typically originate from mobile stations and are referred to as mobile originated messages.
Transceiver (TRX) – A TRX session is a combination of TX and RX, such that a single SMPP session can be used to submit mobile terminated messages and receive mobile originated messages.
Additionally, the Message Centre can establish a SMPP session by connecting to the ESME. This is referred to as an Out bind Session.
The SMPP protocol is basically a set of operations, each one taking the form of a request and response Protocol Data Unit (PDU). For example, if anESME wishes to submit a short message, it may send a submit_sm PDU to the MC. The MC will respond with a submit_sm_resp PDU, indicating the success or failure of the request. Likewise, if a MC wishes to deliver a message to an ESME, it may send a deliver_sm PDU to an ESME, which in turn will respond with a deliver_sm_resp PDU as a means of acknowledging the delivery.
Some operations are specific to an ESME with others specific to the MC. Others may be specific to a given session type. Referring to the submit_sm and deliver_sm examples above, an ESME may send a submit_sm to a MC only if it has established a TX or TRX session with that Message Centre. Likewise, a MC may send deliver_sm PDUs only to ESMEs that have established RX or TRX sessions.
Operations are broadly categorised into the following groups:
Session Management – These operations are designed to enable the establishment of SMPP sessions between an ESME and MC and provide means of handling unexpected errors.
Message Submission – These operations are designed specifically for the submission of messages from ESME(s) to the MC.
Message Delivery – These operations enable a MC to deliver messages to the ESME.
Message Broadcast – These operations are designed to provide Cell Broadcast service within a Message Centre.
Ancillary Operations – These operations are designed to provide enhanced features such as cancellation, query or replacement of messages.
The following sub-sections list each category and its associated operations.
SMPP PDU Name
Description
bind_transmitter
Authentication PDU used by a transmitter ESME to bind to the Message Centre. The PDU contains identification information and an access password for the ESME.
bind_transmitter_resp
Message Centre response to a bind_transmitter PDU. This PDU indicates the success or failure of the ESME’s attempt to bind as a transmitter
bind_receiver
Authentication PDU used by a receiver ESME to bind to the Message Centre. The PDU contains identification information, an access password for the ESME and may also contain routing information specifying the range of addresses serviced by the ESME.
bind_receiver_resp
Message Centre response to a bind_receiver PDU. This PDU indicates the success or failure of the ESME’s attempt to bind as a receiver
bind_transceiver
Authentication PDU used by a transceiver ESME to bind to the Message Centre. The PDU contains identification information, an access password for the ESME and may also contain routing information specifying the range of addresses serviced by the ESME.
bind_transceiver_resp
Message Centre response to a bind_transceiver PDU. This PDU indicates the success or failure of the ESME’s attempt to bind as a transceiver
outbind
Authentication PDU used by a Message Centre to Out bind to an ESME to inform it that messages are present in the MC. The PDU contains identification, and access password for the ESME. If the ESME authenticates the request, it will respond with a bind_receiver or bind_transceiver to begin the process of binding into the MC.
unbind
This PDU can be sent by the ESME or MC as a means of initiating the termination of a SMPP session.
unbind_resp
This PDU can be sent by the ESME or MC as a means of acknowledging the receipt of an unbind request. After sending this PDU the MC typically closes the network connection.
enquire_link
This PDU can be sent by the ESME or MC to test the network connection. The receiving peer is expected to acknowledge the PDU as a means of verifying the test.
enquire_link_resp
This PDU is used to acknowledge an enquire_link request sent by an ESME or MC.
alert_notification
A MC sends an alert_notification to an ESME as a means of alerting it to the availability of an SME.
generic_nack
This PDU can be sent by an ESME or MC as a means of indicating the receipt of an invalid PDU. The receipt of a generic_nack usually indicates that the remote peer either cannot identify the PDU or has deemed it an invalid PDU due to its size or content.
SMPP PDU Name
Description
submit_sm
A transmitter or transceiver ESME, wishing to submit a short message, can use this PDU to specify the sender, receiver and text of the short message. Other attributes include message priority, data coding scheme, validity period etc.
submit_sm_resp
The MC response to a submit_sm PDU, indicating the success or failure of the request. Also included is a MC message_id that can be used in subsequent operations to query, cancel or replace the contents of an undelivered message.
submit_multi
A variation of the submit_sm PDU that supports up to 255 recipients for the given message.
submit_multi_resp
The MC response to a submit_multi PDU. This is similar to the submit_sm_resp PDU. The main difference is that where some of the specified recipients were either invalid or rejected by the Message Centre, the PDU can specify the list of failed recipients, appending a specific error code for each one, indicating the reason the recipient was invalid. Also included is a MC message_id that can be used in subsequent operations to query, cancel or replace the contents of an undelivered message.
data_sm
data_sm is a streamlined version of the submit_sm operation, designed for packet-based applications that do not demand extended functionality normally available in the submit_sm operation. ESMEs implementing WAP over a SMS bearer typically use this operation.
data_sm_resp
The MC response to a data_sm PDU, indicating the success or failure of the request. Also included isa MC message_id that can be used in subsequent operations to query, cancel or replace the contents of an undelivered message.
SMPP PDU Name
Description
deliver_sm
Deliver_sm is the symmetric opposite to submit_sm and is used by a MC to deliver a message to a receiver or transceiver ESME.
deliver_sm_resp
This PDU indicates the ESMEs acceptance or rejection of the delivered message. The error returned by the ESME can cause the message to be retried at a later date or rejected there and then.
data_sm
Data_sm can also be used for message delivery from Message Centre to the ESME. ESMEs implementing WAP over SMS typically use this operation.
data_sm_resp
The ESME response to a data_sm PDU, indicating the success or failure of the MC-initiated delivery request.
SMPP PDU Name
Description
broadcast_sm
A broadcast ESME, wishing to broadcast a short message, can use this PDU to specify the alias, geographical areas, and text of the short message.
broadcast_sm_resp
The MC response to a broadcast_sm PDU, indicating the success or failure of the request. Also included is a MC message_id that can be used in subsequent operations to query or cancel the message.
cancel_sm
This PDU is used to cancel a previously submitted message. The PDU contains the source address of the original message and the message_id returned in the original submit_sm_resp, submit_multi_resp or data_sm_resp PDU. This PDU may also omit the message_id and instead contain a source address, destination address and optional service_type field as a means of cancelling a range of messages sent from one address to another.
cancel_sm_resp
The MC returns this PDU to indicate the success or failure of a cancel_sm PDU.
query_sm
This PDU is used to query the state of a previously submitted message. The PDU contains the source address of the original message and the message_id returned in the original submit_sm_resp, submit_multi_resp or data_sm_resp PDU.
query_sm_resp
The MC returns a query_sm_resp PDU as a means of indicating the result of a message query attempt. The PDU will indicate the success or failure of the attempt and for successful attempts will also include the current state of the message.
replace_sm
The replace_sm PDU is used by an ESME to pass a message_id of a previously submitted message along with several other fields used to update the text, validity period and other attributes of the message.
replace_sm_resp
The replace_sm_resp PDU indicates the success or failure of a replace_sm PDU
If you're a developer and are looking for SMS APIspecs, SDKs, apps and code samples to use ourSMS gateway then you'll find them here.