SMPP API

SMPP Overview

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 Versions

Protocol VersionOwnerDescription
V5.0 2003SMS ForumThis 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 1999SMS ForumThis version of SMPP is based on V3.3 and was intended to provide a fully backward compatible specification to V3.3.
V1.0 – V3.3 1991-1999Aldiscon LtdThe original specification.

SMPP Sessions

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 Outbind Session.

Protocol Operations and PDUs

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 an ESME wishes to submit a short message, it may send a submit_sm PDU to the MC. The MC will respond with asubmit_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.

Session Management Operations

SMPP PDU NameDescription
bind_transmitterAuthentication 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_respMessage 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_receiverAuthentication 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_respMessage 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_transceiverAuthentication 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_respMessage Centre response to a bind_transceiver PDU. This PDU indicates the success or failure of the ESME’s attempt to bind as a transceiver
outbindAuthentication PDU used by a Message Centre to Outbind 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.
unbindThis PDU can be sent by the ESME or MC as a means of initiating the termination of a SMPP session.
unbind_respThis 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_linkThis 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_respThis PDU is used to acknowledge an enquire_link request sent by an ESME or MC.
alert_notificationA MC sends an alert_notification to an ESME as a means of alerting it to the availability of an SME.
generic_nackThis 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.

Message Submission Operations

SMPP PDU NameDescription
submit_smA 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_respThe 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_multiA variation of the submit_sm PDU that supports up to 255 recipients for the given message.
submit_multi_respThe MC response to a submit_multi PDU. This is similar to thesubmit_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_smdata_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_smoperation. ESMEs implementing WAP over a SMS bearer typically use this operation.
data_sm_respThe MC response to a data_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.

Message Delivery Operations

SMPP PDU NameDescription
deliver_smDeliver_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_respThis 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_smData_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_respThe ESME response to a data_sm PDU, indicating the success or failure of the MC-initiated delivery request.

Anciliary Submission Operations

SMPP PDU NameDescription
broadcast_smA 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_respThe 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_smThis 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 originalsubmit_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 optionalservice_type field as a means of cancelling a range of messages sent from one address to another.
cancel_sm_respThe MC returns this PDU to indicate the success or failure of a cancel_sm PDU.
query_smThis 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_respThe 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_smThe 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_respThe replace_sm_resp PDU indicates the success or failure of a replace_sm PDU