SMPP protocol deep dive and troubleshooting

Last update: 2023-09-22
  • Topics:
  • SMS
    View more on this topic

Applies to V7 and V8

Learn how SMPP connections are established and how SMPP exchanges data through PDUs. Understand how to troubleshoot connections.


Hello, everyone, and welcome to the fourth SMS setup of video. I’m Jean-Matthieu, and together we’ll dive deep into the SMS protocol, and we’ll see how to troubleshoot SMPP connections.

First, we’ll see how SMPP connections are made, then we’ll see how SMPP exchanges data by the means of PDUs. Then we’ll see the most useful PDUs, namely the BIND operation, the SUBMIT_SM ans DELIVER_SM operations. And, finally, we’ll have a first approach to how to troubleshoot connections.

And before we begin, this video will show you extract of the Short Message Peer to Peer Protocol Specification. This is the document used to describe the SMPP protocol. It is available on You don’t have to read the whole document, but knowing what’s inside can be helpful to refer to this document when communicating with a provider or searching for precise error code. So, now we’re ready to have a look at SMPP connections.

SMPP uses TCP or SSL, or now TLS, connections. The connection is always initiated by campaign to the provider. SMPP connections are supposed to be permanent and stable, this is very different from HTTP, for example, where connections are made only when needed. It means that there is no polling or no batching of messages, every message is a separate entity.

Inside these connections you send PDUs, meaning protocol data units. Both campaign and the provider can send and receive PDUs at any time. One PDU means one operation and one operation PDU is followed by a RESP PDU, meaning response. Operation PDUs and RESP are matched by a field named sequence_number. So, let’s see what’s inside a PDU. All PDUs are formatted the same way, common length, this is the size of the PDU. Common ID, which is the kind of PDU, the operation. The common stages, which is basically a narrow code. And the sequence number used to match operation and RESP PDUs. And then, depending on the common ID, the PDU can contain more fields. We’ll see a few examples later. So, we said sequence number matches PDUs and RESP, and common stages is an error field. On the right you can see a table of the most common values for a common stages. The most important value here is zero, meaning no error. So, basically when you have issues, if common stages is not zero, then you know something’s wrong. The full table is available in the SMPP specification, but also many providers add specific common status values. So, let’s see a few examples, for example, the BIND operation. A BIND exchanges login and password it’s the first PDU exchanged when establishing a connection. Exchanging login and password is for authentication and authorization purposes, but this is a very weak mechanism so if you want better security you should use TLS. The BIND operation is acknowledged by your BIND_RESP PDU, and also when closing the connection the connector will send an UNBIND operation and wait for UNBIND_RESP. This step is inherited from the old telco protocols, so it’s a bit meaningless nowadays but we have to do it anyway. Beware that some providers call connections bind. If somebody tells you you have five binds available, then they probably mean five TCP connections at any time. There are three kinds of bind operations, they are BIND_TRANSMIITER; so this connection is used to send MTs. BIND_RECEIVER, so this connection can be used to receive MO and SR. And, finally, there is BIND_TRANCEIVER, which is able to both send and receive data. Of course, TRANCEIVER mode is the one to prefer because this is more efficient, and this is what you can find in a BIND operation PDU. We won’t go in too much details right now but you can see the system ID and password in the table for one, which is a BIND operation PDU, and in the BIND_RESP on the right hand table you’ll see common stages which indicates whether the BIND was successful or not. This common stages is really important because the data means whether the connection was successful or not. So, when you have connection issues, this is one of the first things you want to look at.

Then let’s have a look at SUBMIT_SM an DELIVER_SM. SUBMIT_SM is used to send one MT to be delivered on a mobile phone. The PDU contains all the information needed to send an SMS, so the text, the encoding, the recipient phone number, and a lot of other things. The SUBMIT_SM PDU is acknowledged by SUBMIT_SM_RESP, SUBMIT_SM_RESP means that you successfully sent the SMS to the provider, but do not confuse SUBMIT_SM_RESP and an SR. SR means that the SMS was successfully received by the mobile phone, so if you want to know if the SMS was delivered or not you want to have a look at SR not SUBMIT_SM_RESP. Finally, for long message there are two cases, there is the normal way with UDH, there is one SUBMIT_SM PDU per part. So, if your SMS is split in two parts you will see two SUBMIT_SM PDUs, and if you enabled message payload then a single SUBMIT_SM PDU will be sent per long SMS. The provider will have to split the message on their side before sending it to the mobile phone. Here are a few values you can find in the SUBMIT_SM and SUBMIT_SM_RESP PDUs. You can see source address, destination address, which are the phone numbers, data coding indicating the text end coding for this message, SM length indicates the size of the message in bites, and then the short message field that contains the actual message to transfer. And the SUBMIT_SM_RESP PDU contains two important fields that is the common stages. Again, to know if the operation was successful or not, and the message ID, which is used to match the MT and the SR together. Now, let’s talk about DELIVER_SM. DELIVER_SM is for all incoming traffic, both MO and SR. It works basically like SUBMIT_SM, but the other way around. It’s acknowledged by DELIVER_SM_RESP, and you should know that companies 100% synchronous when handling DELIVER_SM. It means that when DELIVER_SM_RESP is sent by campaign you can be sure that all processing is finished and data is secured, so if you have MO or SR issues the first thing to check is the DELIVER_SM_RESP. To differentiate between MO and SR you may have a look at esm-class. This field usually is zero for MO and four for SR. The message ID received from SUBMIT_SM_RESP is sent into the text field of SR, in campaign it is processed by regular expressions. And now a few hints to start troubleshooting SMS connection. So, first, you have to make sure it is actually a SMS connector issue. If you have targeting, preparation, delivery analysis, typology or workflow issues, these are not specifically SMS issues and they can be handled like issues for other channels in campaign, also work with the provider first. You have to ask for concrete proof that the issue is in campaign., meaning a network capture, a log, with the PDUs or instructions of the provider showing something that does not match the SMPP specification. Just saying the connections or the statistics are poor, is not enough. In campaign you can obtain PDU traces via a network capture if you do not use TLS or are using verbal slogans, or Adobe hosted instances, these logs can only be obtained by support. When you have these logs check for potential defects. For example, a non-zero common status in any kind of RESP PDU, remember that if a RESP PDU coming from the provider has a non-zero common status, then the issue is on the provider’s side. It works the same with missing PDUs or duplicated PDUs. Duplicated PDUs very often happen when there was a timeout and a retry, so if you see duplicated PDUs search for missing PDUs, such as expected RESP or PDUs coming too late, also check for RESP PDUs with the wrong sequence number. For example, if you saw PDUs with sequence number one, two and three, and if you see a RESP PDU with a sequence number of 104, then there is probably an issue somewhere. In fact, there is certainly an issue somewhere. And, finally, if the connection is UNBOUD or closed unexpectedly, then there is probably an issue somewhere. Remember that ACC does not keep all connections up at every time, because of technical limitations. But if you see connections going up and down all the time, there may be an issue. When searching for solutions, first talk with the provider, they are here to help you. Also, the SMS tech note has many answers. Don’t hesitate to experiment a bit with external account settings, trial and error is a very effective strategy for timeouts, throughputs or adjustments. And, finally, if you have performance issues, if the performance issue is on the campaign side you have to know that SMS is a very database intensive process. So, having huge workflows running, huge data imports, or big campaigns being prepared while sending SMS may have an impact on throughput.

And this concludes this video. Knowing the SMPP protocol is really useful when troubleshooting or setting up new connections, so I really encourage you to learn more about it and have a look at it when working on SMS with campaign. That was Jean-Matthieu, and thank you for watching. -

On this page