SMPP¶
What is SMPP?¶
Short Message Peer to Peer is a stateful asynchronous TCP protocol that enables clients and servers to communicate by sending PDUs back and forth, in order to send and receive SMS messages as well as delivery reports.
The protocol is often used in the ecosystems of SMS aggregators to provide standard connectivity to each other, and in some cases even between operators and aggregators. However, if you are not operating your own SMS gateway, you would in most cases not benefit much from connecting via SMPP. Instead, we recommend taking a glance at our REST API, which allows simple and familiar means of submitting SMS messages to our systems.
SMPP is not GSM
As is common knowledge, SMS messages consist of one or more segments of 140 bytes, and when using the GSM-7 encoding it is possible to squeeze 160 characters into those 140 bytes. But that is not a part of the SMPP standard.
SMPP clients and servers send PDUs back and forth, and can send SMS messages via the submit_sm and deliver_sm PDUs, both have space for either 255 bytes of encoded text within the PDU or can carry very large text messages outside the PDU itself in the TLV fields.
So it is not impossible that a single PDU carries more than one SMS segment, even in the short_message field on the PDU itself.
Connecting¶
We offer SMPP connectivity for select customers. Contact sales@gatewayapi.com to get access. We use SMPP version 3.4, which is backwards compatible with version 3.3.
We recommend connecting to two hosts. When we perform maintenance, only one host is restarted at a time. By keeping a connection to two hosts, constant connectivity can be achieved.
Modes¶
When binding the connection to an active SMPP session, it is possible to connect as either Transmitter, Receiver or Transceiver.
- Transmitter makes it possible to submit short messages to the system, but MO SMS and DLRs will not be sent back.
- Receiver makes the server read MO SMS and DLRs and submit them back to the connected client.
- Transceiver acts as both Transmitter and Receiver at the same time.
Hostnames¶
We have multiple SMPP servers available:
a.smpp.gatewayapi.comb.smpp.gatewayapi.com
EU setup
If you use our EU setup, replace the .com part with .eu
Most SMPP client allows some degree of configuration. Here is a selection of those that work well for our servers.
| Name | Value |
|---|---|
| Port | 2775 |
| TLS Port | 8775 |
| Bind type | Transceiver, transmitter, or receiver. |
| Enquire link | Every 30 seconds |
| Reconnect delay | 30 seconds |
| System type | Not required |
Server Maintenance¶
We regularly deploy improvements to the SMPP software and the platform it runs on, so you may experience a session being disconnected, but you can reconnect almost immediately. As long as your client can reconnect automatically, no significant downtime or service disruption will occur.
When we roll out changes, only one server instance is taken down at a time, so if you require constant connectivity, we recommend you connect to more than one hostname. That would additionally allow you to distribute the load over multiple instances, thereby minimizing any risk a lost connection would have on your integration.
Credentials¶
After SMPP connectivity has been enabled for your account, you can obtain your SMPP credentials from the system dashboard under “API”, “Credentials”.
Supported Features¶
Commands¶
| Command | Hex | Note |
|---|---|---|
| generic_nack | 0x80000000 |
|
| bind_receiver | 0x00000001 |
|
| bind_receiver_resp | 0x80000001 |
|
| bind_transmitter | 0x00000002 |
|
| bind_transmitter_resp | 0x80000002 |
|
| submit_sm | 0x00000004 |
No support for scheduling delivery times currently |
| submit_sm_resp | 0x80000004 |
|
| deliver_sm | 0x00000005 |
|
| deliver_sm_resp | 0x80000005 |
|
| unbind | 0x00000006 |
|
| unbind_resp | 0x80000006 |
|
| bind_transceiver | 0x00000009 |
|
| bind_transceiver_resp | 0x80000009 |
|
| enquire_link | 0x00000015 |
|
| enquire_link_resp | 0x80000015 |
Only TON values of 0 and 1 are supported for destination addresses. 0 will be interpreted as 1.
MT SMS Delivery¶
Mobile Terminated SMS messages are submitted from the client to the server using the submit_sm PDU as defined in the SMPP specification.
Coding Schemes¶
The SMPP specification contains many different possible encodings, some of which are rarely used, and some of which are unspecified. Needless to say, our SMPP software does not implement the full set of possible encodings, but only the ones most commonly in use.
We also support the older flash SMS flag in the encoding. However if possible, we would recommend using the TLV field dest_addr_subunit as recommended for forwards compatibility by the spec.
The following Data Coding Scheme values are supported:
| DCS | Encoding |
|---|---|
0 |
IA5 / GSM-7 (GSM-7) |
1 |
ASCII |
2 |
Binary |
3 |
Latin1 / ISO-8859-1 |
4 |
Binary |
6 |
Latin/Cyrilic / ISO88595 |
8 |
UCS-2 |
24 |
UCS-2 with flash flag |
240 |
GSM-7 with flash flag |
TLV fields¶
We support the following common TLV fields for submit_sm as well as one custom, which can be used to set the SMS message class.
| Tag | Name | Size | Description |
|---|---|---|---|
0x0005 |
dest_addr_subunit | 1 byte | For flash SMS |
0x0204 |
user_message_reference | 2 bytes | User assigned reference for delivery reports |
0x0424 |
message_payload | octetstring | For sending messages longer than 255 octets |
0x2900 |
message_class | octetstring | To send with a specific GatewayAPI messageclass |
MO SMS Delivery¶
Mobile Originated SMS messages are sent from the server to the client using the deliver_sm PDU as defined in the SMPP specification.
Coding Schemes¶
Much like MT SMS messages, MO messages can be encoded in different ways.
| DCS | Encoding |
|---|---|
0 |
IA5 / GSM-7 (GSM-7) |
3 |
Latin1 / ISO-8859-1 |
4 |
Binary |
8 |
UCS-2 |
Note that messages may occasionally be encoded with UCS-2 even if all the characters in the message could be encoded via GSM-7. This can happen for many different reasons, but the safest approach is to leave the message and encoding as-is and pass it onwards with minimal modification.
This can often cause relatively short messages to become many bytes and can therefore push the text above 140 bytes and even above the 255 bytes the PDU has space for - at which point the message text has to be put in a TLV field, as described below.
TLV Fields¶
We use the following TLV fields when building deliver_sm PDUs for mobile originated messages.
| Tag | Name | Size | Description |
|---|---|---|---|
0x0424 |
message_payload | octetstring | For sending messages longer than 255 octets |
Delivery Reports¶
After submitting messages, one or more delivery reports are generated and sent back to the system that submitted them. These take the form of specially formatted deliver_sm PDUs.
A maximum of 25 000 unacknowledged reports will be kept for 48 hours.
The order of the delivery reports is not guaranteed, so in some cases, you may get an ENROUTE before a DELIVRD.
The message is encoded using Latin-1 / ISO-8859-1.
The delivery report format is as follows:
1 | |
1 | |
The fields sub and dlvrd can be ignored.
The text is the first 20 characters of the user_message_reference TLV if submitted with submit_sm.
The full reference is added in the TLV as well.
The err field is a base 10 representation of our error codes listed in SMS Errors.
Since we only have three digits available, we handle SMS error codes such as 0x107E by keeping 07E and then formatting in base 10 to 126.
If you need to convert back, simply add 0x1000 to the SMPP error code, and format as hex.
The stat field is the following status types:
ENROUTEDELIVRDEXPIREDUNDELIVACCEPTDUNKNOWNREJECTDBUFFERD
Limitations¶
Throttle¶
The server self-imposes a throttle when sending PDUs to a connected client, meaning that if too many PDUs are not responded to, the server will stop sending additional PDUs.
Encoding¶
When accepting submit_sm PDUs, the server checks the encoding and makes sure that the payload can be correctly decoded using the encoding given in the PDU.
Any messages that cannot be decoded correctly will be rejected.
Delivery Reports Distribution¶
When connected with multiple transceivers/receivers using the same account, delivery reports will be distributed between them. So even if one connection submitted an SMS, the delivery report for that SMS can be sent back over another connection.
Priority Overwrite¶
The priority of a submit_sm can be overwritten after it has been accepted in certain cases. Such as when sending priority 3 messages only approved for priority 1 and 2 messages. Check the limitations for details.