SMPP Specification
SMPP Version 3.4 Short Message Peer-to-Peer (SMPP) is a protocol that the telecommunications industry uses to exchange SMS messages between Short Message Service Centers (SMSC) and/or External Short Messaging Entities (ESME).
HollaTags SMPP interface provides support for almost all features of SMPP within the official specification and without proprietary deviation. You can download the full specification here - http://opensmpp.org/specs/SMPP_v3_4_Issue1_2.pdf
The following pages provide details on authentication, configuration, supported pdu and sample smpp client configurations.
SMPP Servers
SMPP Version 3.4 HollaTags has multiple SMPP servers for you to connect to. Each SMPP server offers the ability to connect to it via the regular (plaintext) method, a TLS1.0, or better connection.
We will activate SMPP on your account, and based on your setup you will need to bind into either of the following SMPP servers.
To ensure DLR consistency, we recommend at least 2 bind session, and use Transceiver (TRX) for all bind sessions.
When binding in, always configure your server with the HollaTags' DNS host name provided above and not the IP address.
| Hostname | Port | TLS Port |
|---|---|---|
| smpp1.hollatags.com | 9009 | 9119 |
| smpp-sandbox.hollatags.com | 9009 | 9119 |
smpp-sandbox.hollatags.com is our SMPP sandbox. We typically expect you to connect to this server and test your connectivity before you are moved to any of the live servers.
If you are having trouble establishing a bind, confirm that you are able to reach the HollaTags' SMPP server from your network by testing a simple telnet request to our host and port number from your server. If this is not successful there is most likely an issue with your network. If this is successful, check your SMPP application logs and verify that you are attempting your bind connection with the correct credentials.
SMPP Authentication
Authentication is required to access the HollaTags' SMPP API. The authentication requirements consist of two layers; Firewall and Credentials which are described below.
Firewall Prior to accessing the HollaTags' SMPP API, all accounts must white list their source IP addresses. This can be done within the HollaTags Platform or you can send us a mail on help@hollatags.com
Credentials All SMPP connections require a SystemID and Password to be able to establish your bind to our gateway. Your credentials can be obtained within the HollaTags Platform portal.
If you are having trouble authenticating with the HollaTags API confirm that you have white listed your IP address and that your API credentials are correct. Our SMPP error response to you will also provide some indication of the possible cause of error.
SMPP Configuration
At setup, your SMPP account will have the default values of 4 binds and 50 messages per second.
It might be interesting to note that these values are enforced on a per-server basis. That means that given the above example, you can set up 8 binds in total with a throughput of 100 messages per second when you connect to the two servers.
If you bind on both SMPP server with the same username, your MOs/DLRs will be sent out from either one of the SMPP server. Your will need to accept and process all MOs/DLRs from either servers to avoid lost MOs/DLRs.
To ensure DLR consistency, we recommend you use Transceiver (TRX) for all bind sessions.
Security
We support end-2-end encryption between your server and our servers. If you need to enable this, connect using the TLS port 9119
Supported Message PDU
- bind_transmitter
- bind_receiver
- bind_transceiver
- unbind
- submit_sm
- deliver_sm
- enquire_link
You can bind as a transmitter, receiver or a transceiver. However, if you want to receive delivery reports, you must bind as a transceiver or a receiver.
Command status
We use SMPP command status as per the SMPP v 3.4 standard. Below are some of the HollaTags's specific command_status response codes:
Status and Descriptions
Here's the data converted to a basic HTML table:
| Property Name | Description |
|---|---|
| 0x00000400 | Message Not Routeable. |
| 0x00000401 | Out of Credit. |
| 0x00000402 | Maximum Credit Exceeded |
| 0x00000403 | Account Frozen |
| 0x00000404 | Bad Data. |
| 0x0000040a | Subscriber on DND or Restricted SenderID |
| 0x00000430 | Invalid Payload Length. Used to Limit Short_message and Message_payload to GSM PDU Length. |
| 0x00000431 | Internal Error |
| 0x00000432 | Restricted PDU. Means Message Denied in SPAM Filter. |
| 0x00000433 | DCS Inconsistency. Which Means the Data_coding Value Does not Seem to Match the Encoding in the Payload. |
| 0x000004ff | Internal Error. |
| 0x00000045 | Subscriber on DND. |
| 0x00000058 | Throughput Exceeded. |
Delivery Report Format
Below is the description of each field
| Property | Description |
|---|---|
| id | The unique message ID allocated to the message, this will be hexadecimal in most cases except if otherwise required by the upstream MNO. |
| 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 YYMMDDHHMMSS. |
| done date | The date and time at which the short message reached its final state in YYMMDDHHMMSS. |
| stat | The final status of the message. |
| err | SMPP DLR error code. |
| text | None. |
The short_message field will contain the contents relevant information on the delivery status of your message for DLR and contents of the messaage for MO.
The format is as below:
| Property Name | Value |
|---|---|
| id | 187b876a-ee61-44d8-9086-40631a25fce6 |
| sub | 001 |
| dlvrd | 001 |
| submit date | 200506111011 |
| done date | 200507121720 |
| stat | DELIVRD |
| err | 000 |
| text | Hello world |
Delivery Status
- DELIVRD
- UNDELIV
- EXPIRED
- ACCEPTED
- UNKNOWN
- ENROUTE
- REJECTED
SMPP Client Configuration
Kannel Configuration
Kannel is a popular open source SMPP client software. The configuration below have been provided as an example SMPP connection block that will work out of the box for HollaTags SMPP server. You can make modifications as necessary.
#HollaTags SMSC SMPP
group = smsc
smsc = smpp
smsc-id = HollaTags
allowed-smsc-id = HollaTags
host = smpp1.hollatags.com
smsc-username = "{YOUR CREDENTIAL USERNAME}"
smsc-password = "{YOUR CREDENTIAL PASSWORD}"
port = 9009
receive-port = port
system-type = smpp
wait-ack-expire=0x02
throughput = 50
instances = 4
alt-charset = LATIN1
enquire-link-interval = 30
# you can uncomment the following two lines to enable debug logs
#log-file="/var/log/kannel/HollaTags_SMPP.log"
#log-level=2
PHP Client Configuration
There are some publicly available open-source implementation of SMPP client with PHP. How well this can scale will depend on the mode of implementation.
SMPP Response Codes
These codes are gotten immediately the messages are sent
Here is the HTML table representation for the given properties and descriptions:
| Name | Description |
|---|---|
| 0x00000000 | Success |
| 0x00000400 | Message Not Routeable |
| 0x00000401 | Out of Credit |
| 0x00000402 | Maximum Credit Exceeded |
| 0x00000403 | Message Account Frozen |
| 0x00000404 | Bad Data |
| 0x00000405 | ESME Client Error |
| 0x0000040a | Subscriber on DND or Restricted SenderID |
| 0x00000430 | Invalid Payload Length. Used to Limit Short_message and Message_payload to GSM PDU Length. |
| 0x00000431 | Internal Error |
| 0x00000432 | Restricted PDU. Means Message Denied in SPAM Filter |
| 0x00000433 | DCS Inconsistency. Which Means the Data_coding Value Does not Seem to Match the Encoding in the Payload. |
| 0x000004ff | Internal Error |
| 0x00000045 | Subscriber on DND |
| 0x00000058 | Throughput Exceeded |
SMPP DLR Codes
Common SMPP DLR Codes and Descriptions Here is the HTML table representation for the given properties and descriptions:
| Name | Description |
|---|---|
| UNDELIV err:0dc | Absent subscriber |
| EXPIRED err:206 | Absent subscriber |
| EXPIRED err:21b | Absent subscriber |
| UNDELIV err:21b | Absent subscriber |
| EXPIRED err:023 | Absent subscriber |
| EXPIRED err:054 | Absent subscriber |
| EXPIRED err:027 | Absent subscriber |
| EXPIRED err:053 | Absent subscriber |
| UNDELIV err:439 | Absent subscriber or ported subscriber or subscriber is barred |
| UNDELIV err:254 | Subscriber’s phone inbox is full |
| EXPIRED err:254 | Subscriber’s phone inbox is full |
| EXPIRED err:220 | Subscriber’s phone inbox is full |
| EXPIRED err:120 | Subscriber’s phone inbox is full |
| REJECTD err:008 | Subscriber’s phone inbox is full |
| UNDELIV err:255 | Invalid or inactive mobile number or subscriber's phone inbox is full |
| UNDELIV err:20b | Invalid or inactive mobile number |
| EXPIRED err:215 | Invalid or inactive mobile number |
| UNDELIV err:004 | Invalid or inactive mobile number |
| UNDELIV err:510 | Invalid or inactive mobile number |
| EXPIRED err:20d | Subscriber is barred on the network |
| UNDELIV err:131 | Subscriber is barred on the network |
| UNDELIV err:130 | Subscriber is barred on the network |
| EXPIRED err:222 | Network operator system failure |
| EXPIRED err:602 | Network operator system failure |
| UNDELIV err:032 | Network operator system failure or operator not supported |
| EXPIRED err:306 | Network operator system failure |
| UNDELIV err:008 | Subscriber is on DND |
| 085 | Subscriber is on DND |
| UNDELIV err:065 | Message content or senderID is blocked on the promotional route |
| UNDELIV err:060 | Message content or senderID is blocked on the promotional route |
| UNDELIV err:058 | Absent subscriber |
| EXPIRED err:40a | SenderID not whitelisted on the account |
| UNDELIV err:082 | Network operator not supported |
| UNDELIV err:00a | SenderID is restricted by the operator |
| EXPIRED err:078 | Restricted message content or senderID is blocked |
| UNDELIV err:432 | Restricted message content or senderID is blocked |