Developers
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: smpp3.smsgatewayhub.com
Secondary connection point: smpp1.smsgatewayhub.com
SSL Connection point: smpp2.smsgatewayhub.com |
| port |
Required.8888 (primary and secondary) / 8887 (ssl) |
| timeout keep alive or msg) |
Required. 30 sec |
| system_type |
Optional. |
IMPORTANT:
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:
- DELIVRD
- EXPIRED
- UNDELIV
- ACCEPTD
- UNKNOWN
- ENROUTE
- REJECTD
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):
- DELIVRD
- EXPIRED
- UNDELIV
- ACCEPTD
- UNKNOWN
- ENROUTE
- REJECTD
DATA CODING SCHEME
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.
Example:
“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 |
INFO:
Besides DeliverSM.shortMessage, we also included IMSI as an extra-optional parameter:
Example:
SMPP_VENDOR_SPECIFIC_IMSI = 0x1403
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:
GROOVY
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.
NOTE:
Long SMS feature is not supported for Flash notifications.