Skip to content

SMPP

What is SMPP?

Short Message Peer to Peer is a stateful asynchronous TCP protocol that enabled clients and servers to communicate by sending PDUs back and forth, in order to send and receive SMSes as well as delivery reports of those SMSes.

The protocol is often used 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, we recommend taking a glance at our REST API instead, which allows simple and familiar means of submitting SMSes to our systems.

Connecting

We offer SMPP connection 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 to connect to two hosts. When we do maintainence, only one host is restarted at a time. By keeping a connection to two hosts, constant connectivity can be achieved.

Clients have the option to connect as any of Transmitter, Receiver, and Transceiver.

Hostnames

We have multiple SMPP servers available:

  • a.smpp.gatewayapi.com
  • b.smpp.gatewayapi.com

Most SMPP clients allows some degree of configuration, here is a selection of those that would 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 regurlarily 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 sevice 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 distibute 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 address. 0 will be interpreted as 1.

Coding Schemes

The SMPP specification contains many different possible encodings, some which are rarely used, and some 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, although if possible we would recommend using the TLV field for the same as recommended for fowards compatibility by the spec.

The following Data Coding Scheme values are supported:

DCS Encoding
0 IA5 / GSM 03.38 (GSM7)
2 Binary
3 Latin1 / ISO-8859-1
4 Binary
6 Latin/Cyrilic / ISO88595
8 UCS2
24 UCS2 with flash flag
240 GSM 03.38 with flash flag

TLV fields

We support the following common TLV fields for submit_sm as well as one our own custom for use with message classes.

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

Delivery Reports

Connect with at least one transceiver or receiver to receive delivery reports. A maximum of 25 000 unacknowledged reports will be kept for 48 hours.

The order of the delivery reports are not guaranteed, so in some cases, you may get an ENROUTE before a DELIVRD.

The delivery report format is as in the following examples:

1
id:1390125333 sub:001 dlvrd:000 submit date:2011181054 done date:2011181054 stat:DELIVRD err:000 text:user_message_reference
1
id:1390125333 sub:001 dlvrd:000 submit date:2011181145 done date:2011181145 stat:UNDELIV err:019 text:user_message_reference

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 take a SMS error code like 0x107E, keep the 07E and format 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:

  • ENROUTE
  • DELIVRD
  • EXPIRED
  • UNDELIV
  • ACCEPTD
  • UNKNOWN
  • REJECTD

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 more PDUs.

Encoding

When accepting submit_sm PDUs the server checks the encoding makes sure 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, deliviery reports will be distributed between them. So that even if one connection submitted a SMS, the delivery report for that SMS can be sent back over another connection.