CapeSoft Logo

CapeSoft NetTalk

Download Latest Version
Installed Version Latest Version

NetTalk SMPP (Short Message Peer-to-peer Protocol)



The Short Message Peer-to-Peer (SMPP) protocol is a telecommunications industry protocol for exchanging SMS messages between SMS peer entities such as short message service centers and/or External Short Messaging Entities. It is often used to allow third parties (e.g. value-added service providers like news organizations) to submit messages, often in bulk.

The protocol is based on pairs of request/response PDUs (protocol data units, or packets) . The NetTalk classes handle all encoding and decoding of these packets and provide a simple interface for sending and receiving SMPP packets.

There are three primary classes provided for adding SMS functionality to your application:

This class provides the ability to receive SMS messages, without sending.

Provides the ability to send SMS message, without receiving.

Provides both sending and receiving of SMS messages.

Basic Usage

Add a NetSmpp object to the procedure using the local "NetTalk or NetSimple Object" extension. Select "NetSmppTranceiver" from the Base Class dropdown and enter a name for the object ("Smpp" is used in this example).

First connect to the server:
    ! Connect to a server (Message Center)
    Smpp.Open(server, port)

Then in the Smpp.Process method response to the connection being opened:

    case self.packet.packetType
    of NET:SimpleAsyncOpenSuccessful
        ! Perform a Bind Operation (effectively signs in to the Message Center)
        Smpp.DoBind(user, password, '', number, npi, ton)

When the Message Center sends the response to the Bind operation it is processed in the ProcessPacket method, which is where the rest of the code should be added:

sendMessage           cstring(256)
    case pak.command_id
    of SMPP_BIND_TRANSCEIVER_RESP  ! Bind (Transceiver)
        if pak.command_status = ESME_ROK
            sendMessage = 'Hello World!'
            self.SubmitMessage(sendMessage, '01987654321', 1, 1)
            Message('Bind Failed with error ' & pak.command_status |
                  & ': ' & self.ErrorText(pak.command_status))
    of SMPP_SUBMIT_SM_RESP              ! Message submitted response
        if pak.command_status = ESME_ROK
            Message('Message Sent Successfully')
            Message('Message Sending Failed with error ' & pak.command_status |
                  & ': ' & self.ErrorText(pak.command_status))

        Smpp.DoUnbind()        ! Unbind ("sign out")
    of SMPP_UNBIND_RESP        ! Unbind response, close the connection

Source and Destination Addressing

The SubmitSM (for sending messages) and DataSM (For sending data such as WAP data)  include both a ‘source address’ (message sender) and ‘destination address’ (message recipient). The common concept of a source or destination address is a sequence of digits representing a mobile or fixed-line number. However the reality is more complex. Both addresses comprise of three parts, namely the TON (Type of Number), NPI (Numbering Plan Indicator) and Address (Digit sequence). Every time a message is sent either to or from a mobile, the source and destination addresses comprise of the three parts. This three-part relationship is visible in the PDUs (packets) in the form of the source and destination properties, each of which is an SmppAddress object and contains a .ton, .npi, annd .addr property.

Note: Setting the source.addr field to NULL, will force the MC to default the address to some predetermined value. This is useful for interfaces that are not normally familiar with the notion
of a source address for a short message, e.g. one-way paging systems, voice mail systems.

TON (Type Of Number)

International and National Format

In daily life, people talk about national and international numbers they use for dialing. Such numbers contain an international trunk prefix or the '+' sign, and for many countries a national
trunk prefix. In most European countries the '00' indicates the international trunk prefix whereas the '0' is in many countries the national trunk prefix. In the telecommunications world
where numbers are digitally transmitted through multiple networks, the Type of Number (TON) values of National and International are an easy means of indicating mobile numbers
without dialing prefixes (international trunk prefix, national trunk prefix). The value Unknown is used when number analysis is to be performed for destination routing purposes.

An international TON means that the number starts with the country code followed by the national destination code and the subscriber number. The national destination code is also known as the operator code, operator prefix, and is similar to the fixed-line network area codes. It is common for numbering plans to have multiple national destination codes. In some countries, the wireless and fixed-line network numbering plans are fully integrated. On the mobile terminal the '+' is used as a visible cue to indicate an international number. The '+'
itself is not encoded in the address, it simply translates to TON International.

Example: a mobile sending a message to +4467811223344 is in fact using a TON=1 and dest_addr = 4467811223344 A national TON means that the number starts with the national destination code followed by the subscriber number. Effectively, it is the international number format with the country code stripped off. When a mobile sends a message, unlike the '+' for international number format, there is no visual cue to indicate a national number. It is purely an address encoding value.

Message Centers typically operate with international numbers as the mobile network interface usually requires this. So ESMEs sending message to the MS should expect that a national number will be expanded into international format. ESMEs should expect the source_addr TON of a mobile originated message to be set to international or national, and that the TON can vary from one message to another, even if they are from the same mobile device. This is especially important for application-based database lookups using the mobile number.

Alphanumeric Format

Alphanumeric addressing provides a means of using human-readable names for addresses. In SMPP, an alphanumeric address can carry any digit 0-9 and alphabetical character a-z or
A-Z. For example a voice mail server may send “Voicemail” as a alphanumeric source address and as a means of indicating this, it will set the TON=5. Some mobiles are capable of sending alphanumeric numbers and accomplish this by means of a TON value of 5. NPI is usually set to 0, when TON is 5.

NPI (Numbering Plan Indicator)

NPI is generally set to 1 by mobile devices. Its purpose is to specify the numbering plan of the target device, but because these generally tend to be mobiles, the value is generally set
to 1.

ESME Addresses

Specifying addresses for ESMEs is very much prone to the network operator’s preferences and the message center implementation. An ESME will typically use one of the following


Each operation (and response) supported by SMPP is based on a particular PDU (packet) and the associated response.


"Login" to an MC (Message Center). Can bind as a Receiver (receive messages only), Transmitter (send messages only) or Transceiver (send and receive messages).

A client (ESME) need to Bind to the message center before it can perform any actions.

Enquire Link Operation

This PDU can be originated by either the ESME or MC and is used to provide a confidence check of the communication path between an ESME and a MC. On receipt of this request the receiving party should respond with an enquire_link_resp, thus verifying that the application level connection between the MC and the ESME is functioning. The ESME may also respond by sending any valid SMPP primitive.

Alert Notification Operation

The alert_notification PDU is sent by the MC to the ESME across a Receiver or Transceiver session. It is sent when the MC has detected that a particular mobile subscriber has become
available and a delivery pending flag had been previously set for that subscriber. A typical use of this operation is to trigger a data content ‘Push’ to the subscriber from a WAP
Proxy Server.

Note: There is no associated alert_notification_resp PDU.

Generic NACK Operation

The generic_nack PDU is used to acknowledge the submission of an unrecognized or corrupt PDU. The scenarios for returning this PDU are explained in detail in section 2.8.2


Submit Operations

Message sending operations

submit_sm Operation

This operation is used by an ESME to submit a short message to the MC for onward transmission to a specified short message entity (SME).

data_sm Operation

The data_sm operation is similar to the submit_sm in that it provides a means to submit a mobile-terminated message. However, data_sm is intended for packet-based applications such as WAP in that it features a reduced PDU body containing fields relevant to WAP or packet-based applications.

submit_multi Operation

The submit_multi operation is an enhanced variation of submit_sm designed to support up to 255 different destinations instead of the default single destination. It provides an efficient means of sending the same message to several different subscribers at the same time

Message Replace operation in submit_sm

Though SMPP offers a dedicated replace_sm operation, the submit_sm operation also facilitates replacement of a short message which has been previously submitted but has not yet been delivered to the designated destination.

This feature is designed for applications needing the ability to update an undelivered message. A common application of this feature is with a voicemail system. The first message may read “You have 1 message in your mail box”. If the mobile is not available, the message will remain undelivered and in retry within the message center. If another message is left for the same subscriber, the voicemail server will send another message with the updated text “You have 2 messages in your mail box”. If the replace_flag of the submit_sm PDU is set to 1, then this message should replace the undelivered first message. The result is that the subscriber gets the latest message instead of all messages.

Message Modes

The esm_class field provides a Message Mode feature, which, if supported on the MC, allows an ESME to select the MC message submission/delivery mechanism. The options are as follows:

The esm_class can contain a flag from each of the following groups:

 Message Mode (bits 1-0)

CLASS_DEFAULT equate(000000000b) ! Default MC Mode (e.g. Store and Forward)
CLASS_DATAGRAM equate(000000001b) ! Datagram mode
CLASS_FORWARD equate(000000100b) ! Forward (i.e. Transaction) mode
CLASS_STORE_FORWARD equate(000000011b) ! Store and Forward mode (use to select Store and Forward mode if Default MC Mode is non Store and Forward)

Message Type (bits 2 and 5)

CLASS_DEFAULT_TYPE equate(000000000b) ! Default message Type (i.e. normal message)
CLASS_DELIVERY_RECEIPT equate(000000100b) ! Short Message contains MC Delivery Receipt
CLASS_INTERMEDIATE equate(000100000b) ! Short Message contains Intermediate Delivery Notification

 ANSI-41 specific (bits 5-2)

CLASS_DELIVERY_ACK equate(000001000b) ! Short Message contains Delivery Acknowledgement
CLASS_USER_ACK equate(000010000b) ! Short Message contains Manual/User Acknowledgement
CLASS_CONVERSATION_ABORT equate(000011000b) ! Short Message contains Conversation Abort (Korean CDMA)

GSM Specific (bits 7-6)

CLASS_NON equate(000000000b) ! No specific features selected
CLASS_UDH equate(001000000b) ! UDH Indicator
CLASS_SET_REPLY_PATH equate(010000000b) ! Set Reply Path (only relevant for GSM network)
CLASS_UDHI_REPLY_PATH equate(011000000b) ! Set UDHI and Reply Path (only relevant for GSM network)

Message Types

Types of message determined by the message packet fields.


The registered_delivery field allows an ESME request a delivery receipt for the message. Under normal circumstances, a receipt is typically sent to the ESME when the message reached a final delivery state, regardless of whether the message was actually delivered or not. However the registered_delivery field provides a number of settings that dictate the requirements for generating the receipt. One such example is the value of 2, which requests a receipt only if the message is not delivered when it reaches its final state.


A scheduled message is one that is not immediately dispatched for delivery to the destination SME. Instead the scheduled date provided with the message (ref. dictates the time that the message will become eligible for delivery which requests a receipt only if the message is not delivered when it reaches its final state.


A pre-defined message is a “canned” message that is provisioned on a MC. The ESME specifies the message by providing its ID in the default_msg_id field. The purpose of the predefined message is to relieve the ESME from specifying the actual text, allowing the operator control over what goes to the subscriber.

Message Delivery Operations

Message operations used by the Message Center to send message to a client (ESME).

deliver_sm Operation

The deliver_sm is issued by the MC to send a message to an ESME. Using this command, the MC may route a short message to the ESME for delivery.

data_sm Operation

The data_sm operation is symmetrically used for delivery as it is used to submit messages.

cancel_sm Operation

This command is issued by the ESME to cancel one or more previously submitted short messages that are pending delivery. The command may specify a particular message to cancel, or all messages matching a particular source, destination and service_type.

If the message_id is set to the ID of a previously submitted message, then provided the source address supplied by the ESME matches that of the stored message, that message will be cancelled.

If the message_id is NULL, all outstanding undelivered messages with matching source and destination addresses (and service_type if specified) are cancelled.
Where the original submit_sm, data_sm or submit_multi ‘source address’ is defaulted to NULL, then the source address in the cancel_sm command should also be NULL.

query_sm Operation

This command is issued by the ESME to query the status of a previously submitted short message.

The matching mechanism is based on the MC assigned message_id and source address. Where the original submit_sm, data_sm or submit_multi ‘source address’ was defaulted to NULL, then the source address in the query_sm command should also be set to NULL.

replace_sm Operation

This command is issued by the ESME to replace a previously submitted short message that is pending delivery. The matching mechanism is based on the message_id and source address of the original message.

Where the original submit_sm ‘source address’ was defaulted to NULL, then the source address in the replace_sm command should also be NULL.


[End of this document]
Return to NetTalk Documentation Index