SMS-for-Applications - SMPP

This manual provides the specifications needed to operate the Retarus SMS-for-Applications SMPP Service and complements the SMPP Protocol Specification Ver. 3.4. Any reference to the SMPP Protocol Specification in this manual refers solely to Ver. 3.4.

Although the number of parallel connections that can be set up is almost unlimited, in practice this number is limited by throughput requirements. Please consult your Retarus Technical Consultant to determine the optimal number of connections

PDF definitions

After you have opened a session, you have to send a bind PDU containing the system_id and password.

BIND_TRANSMITTER, BIND_RECEIVER, BIND_TRANSCEIVER

Retarus responds to the bind PDU with the following information.

Field name	Value
command_status	ESME_ROK / ESME_RALYBND / ESME_RINVBNDSTS / ESME_RBINDFAIL (see next table for more information)
system_id	The identical system_id as in the received bind-PDU.
TLV (sc_interface_version)	0x34

The following table explains the meaning of the codes that appear in the command_status field.

Command status	Significance
ESME_ROK (0x00000000)	The bind process was successful.
ESME_RALYBND (0x00000005)	Already bound on this session.
ESME_RINVBNDSTS (0x00000004)	The bind PDU is not expected (e.g., on currently unacknowledged unbinding).
ESME_RBINDFAIL (0x0000000D)	Authorization failed (e.g., the password is incorrect).

UNBIND

If you want to terminate a session, you should send an UNBIND PDU first (Retarus can also send this request). The format of the request is available in Table 4.7 of the SMPP Protocol Specification.

The UNBIND request is answered with an UNBIND_RESP PDU. The UNBIND_RESP PDU results in the termination of the SMPP session.

Both you and Retarus should periodically send an ENQUIRE_LINK and respond to it with an ENQUIRE_LINK_RESP. This is utilized to check that the connection is still “alive”.

SUBMIT_SM

The SUBMIT_SM PDU is crucial for successful SMS transmission. Retarus supports the following formats in the received SUBMIT_SM PDU (please take note of the differences between the following table and Table 4.10 in the SMPP specification):

Field name	Comments
command_status	Ignored; should always be ESME_ROK (0x00000000)
source_addr_ton	Unknown (0x00); international (0x01)
source_addr_npi	Ignored
source_addr	In the Sender ID for source_addr_ton=0x01, we prefix the number with a "+" for further processing.
dest_addr_ton	Unknown (0x00); international (0x01)
dest_addr_npi	Ignored
destination_addr	The recipient phone number (for dest_addr_ton=0x01, we prefix the number with a "+" for further processing)
esm_class	UDHI flag (0x40); see UDH in the short_message entry below. Must be set when short_message contains a User Data Header.
priority_flag	Direct pass through to SMPP outbound
schedule_delivery_time	In accordance with the SMPP specification time format (7.1.1): YYMMDDhhmmsstnnp
validity_period	Ignored (currently not supported)
registered_delivery	No DN (0x00), final outcome-DN (0x01); intermediate notifications are not supported
data_coding	GSM7 (0x00), UCS2 (0x08) and ISO-8859-1 (0x03) are supported. It is recommended to only use GSM7 or UCS2, because for ISO-8859-1 the resulting number of parts maybe confusing. This is because ISO-8859-1 is translated to GSM7 or UCS2 in further processing.
sm_length	The byte length of short_message. For UTF-16, a maximum of 140 bytes are available (2 bytes per characters), and for GSM-7, 160 bytes (1 byte per character). If messages are concatenated, please note that the length of the User Data Header has to be added to the length of each SMS part. So the available bytes per message part is 134 for UTF-16 and 153 for GSM-7.
short_message	Contains the control information and the text. The SMS text is decoded in accordance with the data_coding (see above). If UDHI in esm_class is set: Header with zero-length UDH 0x00: concatenated short message, 8-bit reference number UDH 0x08: concatenated short message, 16-bit reference number
TLVs	Any can be present, but will ignored.

User data header

The UDH is used to encode, e.g., concatenated short messages. It precedes the short message.

If UDHI is present, the following UDH parsing is utilized (Length= the space until the text begins):

Information element identifier	Value
0x00 (concatenated sm with 8-bit reference)	[0x05][0x00][0x03][ref][numberOfParts][partNr][text…]
0x08 (concatenated sm with 16-bit reference)	[0x06][0x08][0x04][ref1][ref2][numberOfParts][partNr][text…]
others	[length][…][text…] Header is skipped, depending on its length, and the remainder is interpreted as single non-concatenated text

[ref], [ref1],[ref2] is a reference that must be equal for all SMS parts.
numberOfParts: is the total number of parts the SMS consists of
partNr: the number an individual part (1,2, …..)

SUBMIT_SM_RESP

SUBMIT_SM_RESP is the acknowledgement that the SUBMIT_SM was received.

Field name	Value
command_status	ESME_ROK (0x00000000) / ESME_RSUBMITFAIL (0x00000045)
message_id	Maximum 8 upper-case hexadecimal characters that are NOT left-padded with zeros.

DELIVER_SM

The table below displays the format used for delivery notifications. Delivery notifications are processed via transmission of a DELIVER_SM PDU (esm_class=0x04) to you.

Field name	Value
command_status	ESME_ROK (0x00000000)
source_addr_ton	0
source_addr_npi	0
source_addr	Sender ID (with leading "+" if international or alphanumeric)
dest_addr_ton	0
dest_addr_npi	0
destination_addr	Destination phone number with leading "+"
esm_class	0x04
data_coding	0
sm_length	Byte length of short_message.
short_message	GSM-7-encoded status text (each byte holds one GSM-7 character)

The following table displays the status mapping from SMSBackend (SMSBE) status to SMPP-deliver_sm-status:

SMSBE status	SMPP status
SUC_FIN	DELIVRD
TIMEOUT	EXPIRED
BLOCKED	REJECTD
FAILED_FIN	UNDELIV
CON_ERR	UNDELIV
INVALID_DST	UNDELIV
NOT_ACC_FIN	UNDELIV
SEND_ERR	UNDELIV
STATUS_ERR	EXPIRED
SUC_ACC	DELIVRD

If the SMSBE process status is not “DONE”, than “REJECTD” is used. Because DNs from SMSBackend are always sent with a final state, the process status should always be “DONE”.

The current short_message text for deliver_sm is:

id:<10digits> sub:001 dlvrd:001 submit date:<10digits> done
date:<10digits> stat:<7chars> err:000 Text:

SMSBE status	SMPP status
id	Always 10 digits; left-padded with zeros
sub	Always 001
dlvrd	always 001
submit date	10 digits with format yyMMddHHmm (date of job receipt)
done date	10 digits with format yyMMddHHmm (date of finished processing: real-delivery time vs. date of DN receive)
stat	One of the above mentioned SMPP-status
err	Always 000
Text	Always empty

id:4294967295 sub:001 dlvrd:001 submit date:1612211026 done
date:1612211026 stat:DELIVRD err:000 Text:

DELIVER_SM (Inbound SMS)

Field name	Value
command_status	ESME_ROK (0x00000000)
source_addr_ton	0
source_addr_npi	0
source_addr	Sender ID (with leading "+") .
dest_addr_ton	0
dest_addr_npi	0

Field name	Value
destination_addr	Destination phone nr with leading "+" (if long code; short codes normally do not have the "+“.
esm_class	UDHI flag (0x40); see UDH in the short_message entry below. Is set, when short_message contains a User Data Header for concatenated messages.
data_coding	0
sm_length	Byte length of short_message
short_message	SMS text encoded according to data_coding. If UDHI is set: UDH 0x00: Concatenated short message, 8-bit reference number. See also the short_message entry in SUBMIT_SM.

DELIVER_SM_RESP

The table below displays the supported data in received DELIVER_SM_RESP PDU for the previous sent DELIVER_SM:

Field name	Value
command_status	ESME_ROK (0x00000000)

A failure command status does not result in an attempt to resend.

GENERIC_NACK PDU and syntax

We send this PDU as a negative response if, for example, you either send a SUBMIT_SM PDU as part of a receiver session or send a DELIVER_SM PDU as part of a transmitter session.

The following error code corresponds to the description in Table 4.9 of the SMPP Protocol Specification:

Field name	Value
command_status	ESME_RINVCMDID (0x00000003)

Additional information

DMZ1LB Firewall permission data:

Login ID = CuNo_smpp01
Port
Password
IP of DMZ1 Loadbalancer (94.199.88.46)

CuNo= your Retarus Customer Number