SMPP specification

Learn more about the various SMPP specifications.

The Short Message Peer-to-Peer (SMPP) is an open, industry standard protocol used by the telecommunication industry for exchanging SMS messages between Short Message Service Centers (SMSC) and SMS application systems. The protocol is a level-7 TCP/IP protocol, which allows fast delivery of SMS messages. The connection between the application and the SMSGATEWAYHUB SMPP server is SMPP version 3.4 (version 3.3 is not supported).

SMPP parameters

Name Description
system_id Required. Provided for each client.
password Required.Provided for each client.
IP address Required.Primary connection point: Secondary connection point: SSL Connection point:
port Required.8888 (primary and secondary) / 8887 (ssl)
timeout keep alive or msg) Required. 30 sec
system_type Optional.


You are allowed to bind as transmitter, receiver or transceiver. In order to receive delivery reports, you must bind as transceiver or receiver.

You’ll receive delivery reports only if your route provides delivery reporting. Delivery reports will be sent equally over all of your currently available sessions capable of receiving them (transceiver or receiver).

By default, you are allowed to bind with 4 sessions. There are no other throughput (TPS) limitations besides internet speed.

PDUs supported:


Delivery report format

id:{message_id} sub:{message_sub} dlvrd:{message_dlvrd} submit date:{message_submit_date} done date:{message_done_date} stat:{message_stat} err:{message_err}

Delivery statuses (message_stat):



If you set DCS 0 or DCS 1 when sending messages, we will treat that as default GSM7 encoding (SMSC Default Alphabet or IA5).

For Latin1 (ISO-8859-1) please use DCS 3 and DCS 8 for sending messages as Unicode (ISO/IEC-10646).

Command status & GSM Error Codes

Each request sent to our system is to receive an acknowledgement in submit_sm resp PDU and is fully compliant with SMPP v 3.4 standard. Proprietary platform command statuses are described here along with platform specific delivery report error codes you may encounter in deliver_sm PDU.

Command status

Command status is received as an response for Submit_SM, on special events, illustrated in the table below.

0x0000000E Invalid credentials, only returned in bind_resp
0x00000022 / 34 Network not covered
0x000000FF / 255 Account has insufficient balance
0x0000000a Invalid source address
0x0000000b Invalid destination address
0x0000000c Duplicate messageID
0x000004a1 System error or channel disabled

GSM error codes

GSM errors which could be provided by smsgatewayhub are listed on General Error Codes.

Additional features

Scheduled delivery

Scheduled delivery is supported over SMPP protocol using the relative time format.


“070605040302100R” - this would mean that the message will be delivered in 7 years, 6 months, 5 days, 4 hours, 3 minutes, 2 seconds and 1 tenth of a second from now.

National Language Shift over SMPP

Along with the standard features of SMPP 3.4, we also provide the national language shift functionality which enables you to use special characters from language-specific character sets.

Number Lookup over SMPP specification

Using the SMSGATEWAYHUB SMPP account, it is possible to request Number Lookup data (IMSI).

In order to use Number Lookup, you can use your default system_id and password, setting system_type = “HLR”(without quotation marks) in Bind PDU.

SubmitSM PDU is used for submitting the Number Lookup request, with the destAddress parameter set to the required destination address. All other parameters will be ignored (srcAddress, TON/NPI, etc).

Once the Number Lookup request is being finalized on the SMSGATEWAYHUB system, you will receive DeliverSM PDU, containing: - IMSI for the required destAddress or - error code in case of failure.

DeliverSM will contain: - short message data with our regular delivery report - IMSI part (“IMSI:xxxxxxxxx”) - serving MSC - additional optional info fields depending on your package.

Optional info fields Type Hex Decimal
Original network name TLVString 0x1412 5138
Original network prefix TLVString 0x140B 5131
Original country TLVString 0x1422 5154
Original country code TLVString 0x1423 5155
Original country prefix TLVString 0x1424 5156
Ported network name TLVString 0x1413 5139
Ported country prefix TLVString 0x1442 5186
Ported network prefix TLVString 0x143e 5182
Ported network country name TLVString 0x143f 5183
Is number ported TLVInt 0x1421 5153
Roaming network name TLVString 0x1414 5140
Roaming network prefix TLVString 0x1419 5145
Roaming country name TLVString 0x1415 5141
Roaming country code TLVString 0x1417 5143
Roaming country prefix TLVString 0x1420 5152
MCCMNC TLVString 0x1416 5142
Price per message For compatibility reasons, price per message is multiplied by 100 TLVInt 0x1418 5144
Serving HLR TLVString 0x1409 5129
Is number correct TLVInt 0x1425 5157


Besides DeliverSM.shortMessage, we also included IMSI as an extra-optional parameter:



Scheduled delivery

Scheduled delivery is supported over SMPP protocol using the relative time format.

addr: 0 0 38591xxxxxxx

addr: 0 0 0000000000

msg: id:40072910491427628 sub:001 dlvrd:001 submit date:1007291049 done date:1007291049 stat:DELIVRD err:000

IMSI:219101100935850 MSC:38591016 HLR:38591xxxxxxx ORN:VipNet PON:VipNet RON:VipNet ROC:HR MCCMNC:21910

opt: (oct: (tlv: 1059) 030000) (byte: (tlv: 1063) 2) (str: (tlv: 30) 40072910491427628) (str: (tlv: 5129)38591xxxxxxx) (str: (tlv: 5138) VipNet) (str: (tlv: 5139) VipNet) (str: (tlv: 5140) VipNet) (str: (tlv:5141) Croatia ) (str: (tlv: 5143) HR) (str: (tlv: 5142) 21910) (int: (tlv: 5144) 1) (str: (tlv: 5145) 91) (str: (tlv: 5152) 385) (int: (tlv: 5153) 1) (str: (tlv: 5154) Croatia ) (str: (tlv: 5155) HR) (str: (tlv: 5156) 385) (int: (tlv: 5157) 1) ) (extraopt: (oct: (tlv: 5123) 323139313031313030393335383530) (oct: (tlv: 5126) 3338353931303136) )

If an error occurred, DeliverSM will be as follows:


Scheduled delivery is supported over SMPP protocol using the relative time format.

addr: 0 0 385915369423

addr: 0 0 0000000000

msg: id:40072910491419819 sub:001 dlvrd:001 submit date:1007291049 done date:1007291049 stat:UNDELIV err:001 IMSI: MSC: ORN:VipNet MCCMNC:

opt: (oct: (tlv: 1059) 030001) (byte: (tlv: 1063) 5) (str: (tlv: 30) 40072910491419819) (str: (tlv: 5138) VipNet) (str: (tlv: 5142) ) (int: (tlv: 5144) 1) (int: (tlv: 5153) 0) (str: (tlv: 5154) Croatia ) (str: (tlv: 5155) HR) (str: (tlv: 5156) 385) (int: (tlv: 5157) 1) )

Flash notifications over SMPP specification

You can use your SMSGATEWAYHUB SMPP account to send Flash notifications. Such notifications are immediately displayed on the mobile phone screen upon arrival and aren’t stored in the memory of the device.

In order to use Flash notifications, you can use your default system_id and password, setting system_type = “NSMS” (without quotation marks) in Bind PDU.

The procedure for submitting Flash notifications is exactly the same as for normal SMS, using SubmitSM PDU. SMSGATEWAYHUB system will automatically convert your message into a Flash notification using the message parameters you have submitted.

Delivery reports will be sent to you using DeliverSM PDU.


Long SMS feature is not supported for Flash notifications.