The SMPP (Short Message Peer-to-Peer) Gateway is a protocol utilized by the telecommunications industry for seamless exchange of SMS messages between Short Message Service Centers (SMSC) and External Short Messaging Entities (ESME). The SMPP protocol is transmitted via TCP/IP, enabling swift and efficient delivery of SMS messages.
The Messaging Platform employs the SMPP v3.4 Protocol Specification Issue 1.5. It is worth noting that our platform is designed to maintain backward compatibility with SMPP v3.3. Therefore, it is recommended to refer to both this document and the SMPP v3.4 Specification v1.5 to ensure a comprehensive understanding of the functionality and features associated with SMPP. Prior familiarity with SMPP is assumed while reading this documentation.
CPaaS Alerts has multiple SMPP servers for you to connect to. Each SMPP server offers the ability to connect to it via the regular (plaintext) method or via a TLS1.0 or better connection.
Here is an overview of the available servers:
| Hostname | Plain Port | TLS Port |
|---|---|---|
| smpp1.mobtexting.com | 3634 | 3635 |
| smpp2.mobtexting.com | 3634 | 3635 |
| Mandatory TLV | Tag value Decimal | Tag value Hex |
|---|---|---|
| PE_ID | 5120 | 1400 |
| Template_ID | 5121 | 1401 |
| Telemarketer_ID(TM_ID) | 51212 | 1402 |
Clients may connect to the Messaging Platform Server multiple numbers of times. This may be of importance if the client wishes to deploy multiple applications simultaneously. To connect to the platform, one needs to specify the following parameters:
IP Address and Port: This is the TCP/IP endpoint on which the ESME should connect to the platform.
Username:
This is the username (system_id) of your account configured on the Platform
Password: Password for the above account. Required for security reasons to prevent unauthorized access to your account.
System_type:
Set the system_type field to smpp.
Interface_version: The client application should connect with the interface_version field set to 0x34 (52 decimal), if it is using SMPP v3.4, otherwise the Platformassumes that the application uses SMPP v3.3.
enquire_link: The application should issue an enquire_link every minute. This will ensure the link stays active even when it is not in use. The Messaging Platform will automatically disconnect any link which is inactive for more than 5mins.
Upon setting up an SMPP account for you, you will receive the maximum number of allowed binds and a designated maximum throughput. Typically, these values may be set to something like 3 binds and 50 messages per second.
It’s worth noting that these values are enforced on a per-server basis. In the example mentioned above, you can establish a total of 9 binds and achieve a combined throughput of 150 messages per second when connecting to all servers.
Please be aware that for maintenance purposes, we can only guarantee the availability of one server at any given time. Therefore, we strongly advise connecting to all servers to ensure uninterrupted service.
CPaaS Alerts Alerts employs a message relaying system that is connection and server agnostic. This means that when you send an MT message via a submit_sm PDU on connection A, you may receive the corresponding DLR in the form of a deliver_sm on connection B, given that both connections are bound with the same username.
Importantly, this holds true even if the connections are established with different servers. For example, if connection A is made to the smpp01 server and connection B to the smpp02 server, the scenario described above would still apply.
Messages may be submitted with either submit_sm or data_sm, using either the
short_message or message_payload fields. The message length may not exceed the
byte limit for the network that the message is being sent to (for example 140 bytes
on GSM networks).
The Platform does not support submit_multi. If the same message has to be sent to multiple destinations, each message must be sent separately.
Concatenated messages are supported by using the User Data Header (UDH), which is included in the message size byte limit.
A positive response to a submit will contain an error code of zero and a non-null message reference.
A negative response will contain a vendor specific error code. The complete set of SMPP Error Codes and their associated values are defined in the following table.
| Error Number | Error Name | Error Description |
|---|---|---|
| 0x00000000 | ESME_ROK | No Error |
| 0x00000001 | ESME_RINVMSGLEN | Message too long |
| 0x00000002 | ESME_RINVCMDLEN | Command length is invalid |
| 0x00000003 | ESME_RINVCMDID | Command ID is invalid or not supported |
| 0x00000004 | ESME_RINVBNDSTS | Incorrect bind status for given command |
| 0x00000005 | ESME_RALYBND | Already bound |
| 0x00000006 | ESME_RINVPRTFLG | Invalid Priority Flag |
| 0x00000007 | ESME_RINVREGDLVFLG | Invalid registered delivery flag |
| 0x00000008 | ESME_RSYSERR | System error |
| 0x0000000A | ESME_RINVSRCADR | Invalid source address |
| 0x0000000B | ESME_RINVDSTADR | Invalid destination address |
| 0x0000000C | ESME_RINVMSGID | Message ID is invalid |
| 0x0000000D | ESME_RBINDFAIL | Bind failed |
| 0x0000000E | ESME_RINVPASWD | Invalid password |
| 0x0000000F | ESME_RINVSYSID | Invalid System ID |
| 0x00000011 | ESME_RCANCELFAIL | Cancelling message failed |
| 0x00000013 | ESME_RREPLACEFAIL | Message recplacement failed |
| 0x00000014 | ESME_RMSSQFUL | Message queue full |
| 0x00000015 | ESME_RINVSERTYP | Invalid service type |
| 0x00000033 | ESME_RINVNUMDESTS | Invalid number of destinations |
| 0x00000034 | ESME_RINVDLNAME | Invalid distribution list name |
| 0x00000040 | ESME_RINVDESTFLAG | Invalid destination flag |
| 0x00000042 | ESME_RINVSUBREP | Invalid submit with replace request |
| 0x00000043 | ESME_RINVESMCLASS | Invalid esm class set |
| 0x00000044 | ESME_RCNTSUBDL | Invalid submit to ditribution list |
| 0x00000045 | ESME_RSUBMITFAIL | Submitting message has failed |
| 0x00000048 | ESME_RINVSRCTON | Invalid source address type of number ( TON ) |
| 0x00000049 | ESME_RINVSRCNPI | Invalid source address numbering plan ( NPI ) |
| 0x00000050 | ESME_RINVDSTTON | Invalid destination address type of number ( TON ) |
| 0x00000051 | ESME_RINVDSTNPI | Invalid destination address numbering plan ( NPI ) |
| 0x00000053 | ESME_RINVSYSTYP | Invalid system type |
| 0x00000054 | ESME_RINVREPFLAG | Invalid replace_if_present flag |
| 0x00000055 | ESME_RINVNUMMSGS | Invalid number of messages |
| 0x00000058 | ESME_RTHROTTLED | Throttling error |
| 0x00000061 | ESME_RINVSCHED | Invalid scheduled delivery time |
| 0x00000062 | ESME_RINVEXPIRY | Invalid Validty Period value |
| 0x00000063 | ESME_RINVDFTMSGID | Predefined message not found |
| 0x00000064 | ESME_RX_T_APPN | ESME Receiver temporary error |
| 0x00000065 | ESME_RX_P_APPN | ESME Receiver permanent error |
| 0x00000066 | ESME_RX_R_APPN | ESME Receiver reject message error |
| 0x00000067 | ESME_RQUERYFAIL | Message query request failed |
| 0x000000C0 | ESME_RINVTLVSTREAM | Error in the optional part of the PDU body |
| 0x000000C1 | ESME_RTLVNOTALLWD | TLV not allowed |
| 0x000000C2 | ESME_RINVTLVLEN | Invalid parameter length |
| 0x000000C3 | ESME_RMISSINGTLV | Expected TLV missing |
| 0x000000C4 | ESME_RINVTLVVAL | Invalid TLV value |
| 0x000000FE | ESME_RDELIVERYFAILURE | Transaction delivery failure |
| 0x000000FF | ESME_RUNKNOWNERR | Unknown error |
| 0x00000100 | ESME_RSERTYPUNAUTH | ESME not authorised to use specified servicetype |
| 0x00000101 | ESME_RPROHIBITED | ESME prohibited from using specified operation |
| 0x00000102 | ESME_RSERTYPUNAVAIL | Specified servicetype is unavailable |
| 0x00000103 | ESME_RSERTYPDENIED | Specified servicetype is denied |
| 0x00000104 | ESME_RINVDCS | Invalid data coding scheme |
| 0x00000105 | ESME_RINVSRCADDRSUBUNIT | Invalid source address subunit |
| 0x00000106 | ESME_RINVSTDADDRSUBUNIR | Invalid destination address subunit |
| 0x0000040B | ESME_RINVBALANCE | Insufficient credits to send message |
The Messaging Platform supports the following two types of data coding schemes: - GSM 03.38 Encoding (default) - Latin 1 (ISO-8859-1) encoding
The default character set is GSM 338. Although for data_coding=1 the character set GSM 03.38 is supported it is NOT RECOMMENDED, as it is known to cause problems with character encoding. Please set data_coding = 3 for ISO-8859-1(if and only if told so explicitly) encoded messages and data_coding=0 for GSM 03.38 encoded messages.
For Unicode messages you have to set data_coding = 8 and the message is expected in UTF-16 Big Endean format.
The Messaging Platform will return a delivery report (Intermediate and/or final depending on the route) for a specific message to the client application when the registered_delivery field, while submitting the message, is set to 1. In order to retrieve the delivery report from our server the client will have to connect to the Messaging Platform in the receiver or transceiver mode
Status and error code which can be returned by Messaging Platform.
| Code | Status | Status Description |
|---|---|---|
| 000 | DELIVRD | Delivered to SIM. |
| 001 | INVALID-SUB | Unidentified subscriber. |
| 002 | INVALID-SUB | Illegal subscriber |
| 003 | ABSENT-SUB | Unidentified subscriber. |
| 004 | HANDSET-ERR | Illegal equipment |
| 005 | BARRED | SMS is prohibited |
| 006 | HANDSET-ERR | MS does not support SMS |
| 007 | HANDSET-ERR | MS receiving error |
| 008 | NET-ERR | Facility not supported. |
| 009 | MEMEXEC | Handset memory full |
| 010 | ABSENT-SUB | Absent subscriber |
| 011 | FAILED | SMSC system failure |
| 012 | NET-ERR | Gateway mobile switching error |
| 013 | MOB-OFF | Mobile handset switched off |
| 014 | FAILED | SMS undelivered due to roaming limitation |
| 015 | INVALID-SUB | Unidentified subscriber |
| 016 | HANDSET-BUSY | Subscriber is busy. |
| 017 | NET-ERR | Resource cannot be used at GMSC level |
| 018 | SERIES-BLK | Series blocked |
| 019 | NET-ERR | Submission error or invalid input data |
| 020 | BARRED | CUG reject |
| 021 | EXPIRED | SMS timeout |
| 034 | UNDELIV | Unknown Error |
| 045 | FAILED | Unknown Error |
| 099 | UNDELIV | Unknown Error |
| 400 | SERIES-BLOCK | Series has been temporary / permanently blocked. |
| 401 | NO-CREDITS | Credit exhausted. |
| 402 | NO-ACCOUNT | Invalid account. |
| 403 | SERVER-ERR | Unknown Error |
| 404 | INV-NUMBER | Invalid destination number |
| 405 | SERVER-ERR | ESME client error |
| 406 | SERVER-ERR | ESME client error |
| 407 | SPAM | Sent illegal content |
| 408 | DNDNUMB | Number registered in dnd database. |
| 430 | SERVER-ERR | Unknown Error |
| 431 | SERVER-ERR | Unknown Error |
| 432 | SERVER-ERR | Unknown Error |
| 433 | SERVER-ERR | Unknown Error |
| 450 | BLACKLST | Number blocklisted to receive messages |
| 451 | SNDR-BLOCK | Sender Id been blocked |
| 452 | TEMPLATE-NOT-FOUND | No matching templates |
| 453 | INV-TEMPLATE | Message rejected as template not allotted for ESME |
| 454 | INV-SENDER | Message rejected as sender id not allotted for ESME |
| 455 | NOT-OPTIN | Message rejected as number not in optin list |
| 456 | OPTOUT-REJ | Rejected as number optout to receive messages |
| 457 | PROMO-TMOUT | Promotional time exceeded |
| 458 | REJECTED | Unknown Error |
| 459 | NOTALLOWED | Country not allowed to send sms |
| 460 | DUPLICATE | Same content sent |
| 461 | UNDELIV | Unknown Error |
| 462 | FAILED | Unknown Error |
| 463 | THROTTLED | Maximum Sent Limit is Reached |
| 778 | REJ-MULTIPART | All message parts are not delivered to handset |
| 777 | DLT-REJECTED | Invalid Sender-Id or Invalid Template |
| 780 | DLT-INV-TMID | Invalid DLT telemarketer Id |
| 781 | DLT-INV-ENTITY | Invalid Entity DLT Id |
| 782 | DLT-INV-TM-ID | Invalid DLT Template Id |
| 783 | DLT-TM-VAR-EXECEED | Template variable exceeded 30 chars |
| 784 | DLT-ENTITY-NOT-FOUND | Entity Id not found |
| 785 | DLT-TM-BLACKLST | Template Id blacklisted |
| 786 | DLT-ENTITY-BLACKLST | Entity Id blacklisted |
| 787 | DLT-HEADER-INACTIVE | Sender Inactive |
| 788 | DLT-TM-INACTIVE | Template is Inactive |
| 789 | DLT-SENDER-NOT-REG-TM | Sender not registered for template |
| 790 | INV-PROVISION | Sender Invalid Provision |
| 791 | INV-SERVICE | Invalid Service Type |
| 792 | INV-SCHEDULE | Invalid Schedule |
“Subscribe here to get SMPP messages DLRS via Webhook, refer to Subscription”
