SMPP delivery report format
SMPP delivery reports are sent by the SMPP Server, to the SMPP client after the text messages was successfully delivered to the handset. The original SMS is submitted by the SMPP client using an smpp submit_sm request. When the submit_sm is accepted by the SMPP server, it returns a submit_sm_resp response, with an sms reference ID. The delivery report comes in at a later date. It contains the time of delivery and the sms reference ID that identifies the sms. The document below explains the contents of an SMPP delivery report PDU and gives you a delivery report example.
What is the smpp delivery report format
And smpp delivery report is received as a standard text message. The messages text has a special format, that contains various fields about the originally submitted sms. These fields can be used to determine the state of the sms delivery.
Delivery report example
Delivery report received. +44251234567->+0000000 'Delivered; To: +44251234567; At: 2022-10-03 12:07:00; Ref: 636445148; id:636445148 sub:000 dlvrd:001 submit date:2210031207 done date:2210031207 stat:DELIVRD err: text:' Successful delivery reported to admin@localhost. Task ID: cdfd66e1-880e-4ead-a559-7ca46d9ec669. Delivered; To: +44251234567; At: 2022-10-03 12:07:00; Ref: 636445148; id:636445148 sub:000 dlvrd:001 submit date:2210031207 done date:2210031207 stat:DELIVRD err: text:
How to receive an SMPP delivery report
To receive an SMPP deliver report
- Connect the SMPP client
- Bind as transceiver
- Send the SMS using the submit_sm pdu
- Record the SMS ID of the submit_sm_resp
- Wait for the SMS to arrive to the mobile
- Receive the SMS delivery report pdu
- Match the SMS ID to the submitted message
- Record the sms delivery timestamp
SMPP deliver report parameters
SMPP supports delivery receipts / reports (DLRs) for SMS messages so that your application can determine delivery outcomes.
The returning of a message delivery receipt / report (DLR) is dependent on the value set in the registered_delivery field of the message originally sent from the ESME to the MC in an submit_sm operation. This can be configured for non-delivery and delivery-only scenarios that can result in circumstances where the receipt will not be returned. Message delivery receipts are returned in the deliver_sm and data_sm operations.
The following fields are relevant in the deliver_sm and data_sm operations when used for transmitting delivery receipts.
- source address (i.e. source_addr_ton, source_addr_npi, source_addr) - The source address will be taken from the destination address of the original short message, which generated the delivery receipt. The receipt appears as if it emanated from the recipient of the original registered message.
- destination address (i.e. dest_addr_ton, dest_addr_npi, destination_addr) - The destination address will be taken from the source address of the original short message, which generated the delivery receipt. The receipt is addressed to the SME that originally sent the registered message.
- esm_class - Bit 2 of the esm_class is set to 1 to indicate that the message is an MC Delivery Receipt. If bit 5 is set, then the message is an Intermediate Notification.
- message_state TLV - Indicates the final state of the original message. See Message states below.
- network_error_code TLV - See Error codes below.
- receipted_message_id TLV - Message ID that was returned to the ESME by the MC in the submit_sm_resp PDU.
MC Delivery Receipt
This message type is used to carry a MC delivery receipt. The MC, on detecting the final state of a registered message, would normally generate a new receipt message addressed to the originator of the first message. The MC Delivery Receipt is then delivered to the ESME in a deliver_sm or data_sm operation.
ESME-to-MC: Set bits 0 and 1 in a submit_sm operation registered_delivery field to request an MC Delivery Receipt.
Bit 1 | Bit 0 | Meaning |
---|---|---|
0 | 0 | no receipt |
0 | 1 | receipt requested when final outcome is delivery success or failure |
1 | 0 | receipt requested when final outcome is delivery failure |
1 | 1 | receipt requested when final outcome is delivery success (SMPP v5 only) |
MC-to-ESME: Bit 2 in the esm_class field of a deliver_sm indicates the receipt is an MC Delivery Receipt.
Intermediate Notification
An intermediate notification is a special form of message that the MC may send to an ESME for a mobile terminated message delivery. It provides an intermediate status of a message delivery attempt.
Typical uses are to report the outcome of delivery attempts made during the message’s retry lifetime within the MC. This could be used to track the various reasons why a message is not delivered to its destination and use this to profile the subscriber’s availability.
Support for Intermediate Notification functionality is specific to the MC implementation and the MC Service Provider and is beyond the scope of this specification.
ESME-to-MC: Set bit 4 in a submit_sm PDU registered_delivery field to request an Intermediate Notification.
MC-to-ESME: Bit 5 in the esm_class field of a deliver_sm indicates the receipt is an Intermediate Notification.
Receipt in short_message field
Many pre-v3.4 APIs and Message Centres supporting v3.3 are likely to have a means of passing receipt information within the short_message field. This applies to MC Delivery Receipts and Intermediate Notifications. The format specifics of this information are SMS gateway and SMSC platform specific and beyond the scope of the specification. However, the following shows the approach typically taken:
id:123A456B sub:1 dlvrd:1 submit date:1702281424 done date:1702281424 stat:DELIVRD err:0 text:
The fields are specified as follows:
Field | Size (octets) | Description |
---|---|---|
id | Variable | The message ID allocated to the message by the SMSC when originally submitted. |
sub | 3 | Number of short messages originally submitted. The value may be padded with leading zeros. |
dlvrd | 3 | Number of short messages delivered. The value may be padded with leading zeros. |
submit date
|
10 |
The time and date at which the short message was submitted. In the case of a message which has been replaced, this is the date that the original message was replaced. The format is as follows: YYMMDDhhmm where: |
done date
|
10 | The time and date at which the short message reached it’s final state. The format is the same as for the submit date. |
stat | 7 | The final status of the message. See Message states below. State text may be abbreviated. |
err | 3 | A network or SMSC error code for the message. See Error codes below. |
text | 20 | Unused field, result will be blank. |
Ozeki SMPP improvements
As we have implemented a very large number of SMPP connections we have found the following issues in various implementations:
Finding 1:The value of the ID field in the delivery report (which we call Submit Reference in Ozeki) is often different from the ID we receive from the SMS service provider. The most common difference is that the original ID is returned as a standard integer number and the ID in the delivery report is returned as a hexadecimal number. This can also happen vice versa. The good thing is that in this situation, when converted back the two numbers match, so the delivery reports can match. The Ozeki SMS implementations perform various checks and can handle the described situation properly.
Finding 2:The value of the date fields often come in non-standard format. Ozeki currently parses the date fields using the following patterns. You may also define a custom date field pattern on the configuration form of the software.
- "yyMMddHHmm",
- "yyMMddHHmmss",
- "dd-MMM-yyHH:mm",
- "dd-MMM-yyHH:mm:ss",
- "dd-MMM-yy HH:mm",
- "dd-MMM-yy HH:mm:ss",
- "yyyyMMddHHmmss",
- "yyyyMMddHHmm",
- custom
Message states
The following is a list of allowable states for a short message. The MC returns the message_state value to the ESME as part of the query_sm_resp, query_broadcast_sm_resp or deliver_sm delivery receipt PDU.
Intermediate states are states that can change. Final states are states that represent an end-of-life state for a message.
For example, a message in retry may return an ENROUTE state. At some point in the future, this message will either expire or be delivered. The state will then progress to EXPIRED or DELIVERED. Thus, a message in ENROUTE state is said to be in an intermediate state.
A message in DELIVERED or EXPIRED state cannot progress to another state. These states are therefore final states.
Message State | Value | Type |
---|---|---|
SCHEDULED | 0 | Intermediate |
The message is scheduled. Delivery has not yet been initiated. A message submitted with a scheduled delivery time may return this state when queried. This value was added for SMPP v5.0. MCs supporting earlier version of SMPP v3.3 and SMPP v3.4 are likely to return ENROUTE for scheduled messages. | ||
ENROUTE or EN_ROUTE |
1 | Intermediate |
The message is in enroute state. This is a general state used to describe a message as being active within the MC. The message may be in retry or dispatched to a mobile network for delivery to the mobile. | ||
DELIVERED | 2 | Final |
Message is delivered to destination. The message has been delivered to the destination. No further deliveries will occur. | ||
EXPIRED | 3 | Final |
Message validity period has expired. The message has failed to be delivered within its validity period and/or retry period. No further delivery attempts will be made. | ||
DELETED | 4 | Final |
Message has been deleted. The message has been cancelled or deleted from the MC. No further delivery attempts will take place. | ||
UNDELIVERABLE | 5 | Final |
Message is undeliverable. The message has encountered a delivery error and is deemed permanently undeliverable. No further delivery attempts will be made. Certain network or MC internal errors result in the permanent non-delivery of a message. Examples of such errors would be an unknown subscriber or network error that indicated that the given destination mobile was denied SMS service or could not support SMS. |
SMPP Delivery Receipt Error Codes
Error codes returned in delivery receipts are used to indicate any error situation encountered when attempting to deliver a message. Error codes are SMS gateway and SMSC platform specific. However, the following shows an approach often taken:
Code Meaning 1 MT number is unknown in the MT network’s HLR 2 MT number is unknown in the MT network’s HLR 5 MT number is unknown in the MT network’s MSC 9 MT number is classed as an illegal subscriber in the MT network’s MSC 11 MT HLR sends back a “Teleservice not provisioned” error in response to the SRI 12 MT handset is listed as an Illegal device on the MSC. 13 Customer is barred according to the MT HLR from receiving SMS 15 MT customer is part of a CUG that is not allowed to receive SMS 21 SMS not supported in the MT network. 22 SMS not supported in the MT MSC 31 MT handset is busy. The signalling control channel is in use. (Probably receiving another SMS at the same time) 32 GPRS – As above 34 System failure in the MT network. 35 Data Missing in either the MT HLR or MSC 36 Unexpected data value received in response to a FSM or SRI 40 Memory capacity exceeded on the MT handset 41 MT handset protocol error 42 MT handset is not equipped to support SMS 43 Short message type “0” not supported by the MT handset. 44 MT network unable to replace the SMS on the MT customers’ handset 45 Unspecified protocol error on the MT handset 46 Message class not supported on the MT handset 47 Unspecified DCS (Data coding scheme) error on the MT handset 48 Transfer layer PDU not supported by MT handset 49 SIM card full on MT handset 50 MT handset’s SIM is unable to store the message 51 Error in MT handset 52 Memory capacity exceeded on the MT handset 53 SIM application toolkit busy on the MS handset 54 SIM data download error on the MT customer’s handset 55 Unspecified MS handset error 60 Absent subscriber. No reason known 61 Absent subscriber due to phone being switched off 62 Absent subscriber due to phone out of coverage/flat battery 63 Absent subscriber due to roaming restriction/restricted area 64 Absent subscriber due to being deregistered in the HLR 65 Absent subscriber due to being purged in the VLR (off for 24+ hours) 66 Absent subscriber (GPRS) cannot be paged by the SGSN 67 Absent subscriber due to GPRS detached 68 Absent subscriber due to deregistration in the HLR (GPRS) 69 Absent subscriber due to GPRS MS purged in VLR 70 Absent subscriber due to unidentified subscriber on the MSC that the FSM was sent to. 71 Absent subscriber due to unidentified subscriber on the SGSN
How to test SMPP delivery reports
You can create an SMPP simulator configuration, to test SMS delivery reports. In the simulator the tester connection can return successful delivery and failed delivery reports. It will do this if you configure "Delivery report request" on the "Advanced" tab page of the SMPP Tester connection's configuration form. If you have this option enable a delivery report will be returned for each submitted SMS at a random later date with a random status of successful or failed delivery.
FAQs
What is a delivery report?
When sending an SMS message, confirmation of its arrival at the recipient's phone
is crucial. SMS employs a two-step confirmation system to ensure this.
Upon submitting your message to the mobile network's Short Message Service Centre
(SMSC), you receive a "message submission report." This report signifies that
the SMSC has accepted your message for delivery. It also includes a unique
identifier, often referred to as a "message reference" or "callback ID," that
allows tracking the message within the SMSC system.
After acceptance, the message is stored in the SMSC until delivery becomes
possible. This might be delayed if the recipient's phone is switched off,
potentially extending the wait to days.
Once the recipient's phone becomes available, the message is delivered. Upon
successful delivery, a "delivery report" is sent back to the sender as a separate
SMS message.
This confirmation SMS contains:
- Recipient's phone number: Verifies the intended recipient received the message.
- Message reference (callback ID): Matches the identifier from the original submission report, providing a clear link between the two stages.
- Delivery timestamp: Provides the exact time the message reached the recipient's phone.
Can I adjust how long a message is stored in the SMSC?
While SMS messaging offers a convenient way to communicate, ensuring a message
reaches its recipient promptly is crucial. This is where the concept of the
"validity period" comes into play.
The validity period refers to the timeframe an SMS message is stored in the
Short Message Service Centre (SMSC) when the recipient's phone is unavailable.
If the message remains undelivered after this period elapses, it's automatically
deleted from the SMSC, preventing a delayed delivery.
Benefits of Utilizing Validity Period:
- Time-Sensitive Messages: Imagine sending a text about a time-sensitive event, like a live TV program. Setting an appropriate validity period ensures the message isn't delivered after the event has concluded, rendering it irrelevant.
- Network Efficiency: By preventing unnecessary delivery attempts to unavailable phones, the validity period optimizes network resources.
It's important to remember that not all mobile networks offer user-configurable validity periods, and some may require user activation for delivery reports (confirmation that the message reached the recipient).
More information
- SMPP specification
- SMPP PDU logging
- Throttling error
- How to use SMPP API with programming languages
- Secure SMPP connection over SSL TLS
- SMPP delivery report format
- What is an SMPP simulator
- SMPP error codes
- SMPP network bandwidth calculator
- How to send a test SMPP SMS message
- SMPP PDU decode
- SMPP Character encoding
- SMPP wireshark