SMPP Integration (English version)

Integration via SMPP

The Short Message Peer to Peer (SMPP) protocol is an open protocol designed to provide an interface for flexible data communication for the transfer of short messages between a Short Message Service Center (SMSC) and an SMS application.

The term SMSC is used when referring to the server entity of the SMPP connection. In the case of the client entity of the SMPP connection, the name adopted by the protocol is ESME (External Short Message Entity).

Version 3.4 of the SMPP protocol allows:

  • Transmit messages from an ESME to a single or multiple destinations via SMSC;
  • That an ESME can receive messages from a mobile terminal via the SMSC;
  • Send messages with confirmation of receipt;
  • Cancel or reset messages;
  • Query the delivery status of a particular message;
  • Schedule message delivery by selecting the date and time of delivery;
  • Select the message transmission mode, ie datagram or store and forward
  • Define the encoding type of the message data;
  • Set a validity period for the message;
  • Associate a service type for each message.

The following table presents the parameters for accessing and sending messages to the SMSC Zenvia:

Access Parameters Value Mandatory (Yes/No) Comments
Host Name smpp.zenvia360.com Yes Name of the SMSC Zenvia.
Port 8057 Yes Port of the SMSC Zenvia.
system_id Yes Username – Request your account username to our Customer Service team.
password Yes Password – Request your account password to our Customer Service team.
interface_version 34 Yes SMSC Zenvia only supports version 3.4 of the SMPP protocol. Version 3.3 is not supported.
Upload parameters (PDU: submit_sm) Value Mandatory (Yes/No) Comments
type_name submit_sm Yes
command_id 4 = 0x00000004 Yes
command_status 0 = 0x00000000 Yes
service_type NULL Yes
source_addr_ton 1 Yes
source_addr_npi 1 Yes
source_addr NULL Yes Attributed by SMCS Zenvia, except for dedicated short codes previously registered.
dest_addr_ton 1 = 0x00000001 Yes
dest_addr_npi 1 = 0x00000001 Yes
destination_addr Yes Message destination phone.PPPAAAANNNNNNNNN, Brazil Example: 5511999887766 where 55 = country, 11 = area, 99887766 = destination mobile phone number of the message.
data_coding 0x00 -> GSM_7BIT

0x01 -> US_ASCII

0x03 -> ISO_8859_1

0x08 -> UTF-16BE

Yes GSM_7BIT: https://en.wikipedia.org/wiki/GSM_03.38

ISO_8859_1: https://en.wikipedia.org/wiki/ISO/IEC_8859-1

UTF16: https://en.wikipedia.org/wiki/UTF-16

esm_class 3 = 0x00000003 Yes

 

NOTE: The maximum number of concurrent BINDs per account is 20.

Timers

To ensure the connection will not be closed due to inactivity between the ESME and SMSC, an enquire_link PDU should be sent every few seconds. Zenvia SMSC, after establishing the connection, sends an enquire_link every 5 seconds, with a response time of 2 seconds. In case an enquire_link_resp (or any other response to a PDU) is not received in this time interval, the connection will be closed.

SMPP Protocol

The SMPP protocol traverses over TCP/IP and is based on sessions between each ESME x SMSC entity through which the Protocol Data Unit (PDU) packets are sent, containing the information of each specific SMPP operation. It uses a system of exchange of messages and confirmations of receipt to guarantee the reliability of the transactions. The SMPP protocol defines:

  • A set of operations for the exchange of messages between ESME and SMSC;
  • The data that one entity can exchange with another during an SMPP operation.

All SMPP message sending operations must be followed by a reply message. The exception to this rule is in the case of the ALERT_NOTIFICATION message, which does not require a response.

The three distinct groups of SMPP message transactions are as follows:

  • Messages sent from ESME to SMSC;
  • Messages sent from the SMSC to ESME;
  • Messages exchanged between ESME and SMSC simultaneously;

Figure 1 bellow shows the three possible types of section within the SMPP protocol. Note the direction the messages are sent.

  • Transmitter Connection – Used for sending messages through a BIND TRANSMITTER
  • Receiver Connection – Used for receiving messages through a BIND RECEIVER
  • Transceiver Connection – Used for both sending and receiving messages through a BIND RECEIVER

SMPP-figura1-transmitter-receiver-transceiverFigure 1 – Sections diagram of the SMPP protocol – Transmitter, Receiver and Transceiver

An SMPP session between an ESME and an SMSC is initiated by establishing a TCP/IP link between these two entities. Next, ESME, the client entity of the SMPP session, requests the connection, called BIND . If this entity wants to send messages, it must make a “BIND TRANSMITTER”, if it wants to receive messages, it must make a “BIND RECEIVER” and if it wants both to send and to receive, it must do either a “BIND TRANSMITTER” and a “BIND RECEIVER” or Simply a “BIND TRANSCEIVER”. The steps for this connection are described below:

  • OPEN (Connected via TCP/IP, waiting for BIND) ESME already has a logic path via TCP/IP, but has not yet requested the opening of the SMPP connection;
  • BOUND_TX ESME has requested to open the SMPP transmitter connection by sending a bind_transmitter Protocol Data Unit (PDU). Upon receiving this PDU, the SMSC returns a bind_transmitter_resp, stating whether or not it accepted the connection. If the connection is established, ESME will already be able to send messages to the SMSC;
  • BOUND_RX ESME has requested to open the SMPP receiver by sending a bind_receiver PDU. Upon receiving this PDU, the SMSC returns a bind_receiver_resp, stating whether or not it accepted the connection. If the connection is established, ESME will already be able to receive SMSC messages;
  • CLOSED ESME requested disconnection from SMSC.

Another SMPP operation is OUTBIND , which is the SMPP message sent by the SMSC to ESME, requesting that ESME send a BIND_RECEIVER . Notice that the ESME rule requesting the connection was not broken, since the SMSC did not establish the connection, but ESME. The diagram below illustrates this situation:

SMPP-figura2-outbind-esme-smcs
Figure 2 – OUTBIND diagram between ESME and SMSC

The following table shows how supported and unsupported features by Zenvia’s SMSC:

Supported Messaging Features Available (Yes/No/Partial) Comments
Alphanumeric Originators Partial Limited by Mobile Operators. Please contact our sales team.
Shortcode Originators Yes
Numeric Originators Yes
Special Character Support within Originator No
Supports dynamic originators? No
Standard Text Yes
Standard Binary Yes
Standard Unicode Yes
Delivery Receipts Yes
Support for Concatenated Text Yes Each message part must be up to 153 characters.
Support for Concatenated Binary Yes
Support for Concatenated Unicode Yes
Full Character-set support Yes
Flash Message (message type 0) Yes
Wap-Push No
Local/Dynamic timestamp support No

For further information, please see the official SMPP protocol manual.

Delivery Receipt

A delivery receipt (DLR) is sent by the SMSC as a deliver_sm PDU. This PDU is the same one used to send short messages (MO). In order to verify if this PDU is a DLR, it is necessary to check the esm_class field: if the bit 2 is set (0x04), then it is a DLR.

The delivery information can be found in the short_message field (ASCII encoded). It has the following structure:

id:3e058590 sub:001 dlvrd:001 submit date:1711231558 done date:1711231558 stat:REJECTD err:000 text:
  • id: message ID
  • sub: the number of short messages originally submitted
  • dlvrd: the number of short messages delivered
  • submit date: the date and time at which the short message was submitted, in YYMMDDhhmm format
  • done date: the date and time at which the short message reached its final state, in YYMMDDhhmm format
  • stat: the final status of the message
  • err: additional status code from SMSC Zenvia (check table below)
  • text: (none)

Status Codes

Below you will find the values for the message status:

Code Description
DELIVRD Message is delivered to destination
EXPIRED Message validity period has expired
DELETED Message has been deleted
UNDELIV Message is undeliverable
ACCEPTD Message is in accepted state
UNKNOWN Message is in invalid state
REJECTD Message is in a rejected state

 

The additional status codes can be found in the following table:

Code Description
000 Message Sent
002 Message successfully canceled
010 Empty message content
011 Message body invalid
012 Message content overflow
013 Incorrect or incomplete ‘to’ mobile number
014 Empty ‘to’ mobile number
015 Scheduling date invalid or incorrect
016 ID overflow
017 Parameter ‘url’ is invalid or incorrect
018 Field ‘from’ invalid
021 ‘id’ field is mandatory
080 Message with same ID already sent
100 Message Queued
110 Message sent to operator
111 Message confirmation unavailable
120 Message received by mobile
130 Message blocked
131 Message blocked by predictive cleansing
132 Message already canceled
133 Message content in analysis
134 Message blocked by forbidden content
135 Aggregate is Invalid or Inactive
136 Message expired
140 Mobile number not covered
141 International sending not allowed
145 Inactive mobile number
150 Message expired in operator
160 Operator network error
161 Message rejected by operator
162 Message cancelled or blocked by operator
170 Bad message
171 Bad number
172 Missing parameter
180 Message ID not found
190 Unknown error
200 Messages Sent
210 Messages scheduled but Account Limit Reached
240 File empty or not sent
241 File too large
242 File readerror
300 Received messages found
301 No received messages found
400 Entity saved
900 Authentication error
901 Account type not support this operation
990 Account Limit Reached – Please contact support
998 Wrong operation requested
999 Unknown Error

 

PDU Examples

In this link you can find PDU examples in pcap format.