Last Updated: Wednesday, May 19, 2021
External Short Message Entities (ESMEs) can request intermediate and final delivery statuses for Mobile Terminated (MT) messages. Delivery Receipts are sent back to the ESME via DeliverSM Protocol Data Units (PDUs), and can be sent on any of the RX or TRX binds that are bound to the Short Message Service Center (SMSC).
Note: SMPP spec does not support timezone for submit done date and remote done date in DeliveryReceipts. Vibes works with carriers to understand the contextual timezone and use that to convert the DLR dates (submit and done) to Universal timezone to make it timezone agnostic.
The ESME can request notifications to track the progress of a message before the final delivery outcome of the message. The only intermediate notification supported right now is when the message is submitted to the carrier.
Final Delivery Notifications
These will have the final delivery outcome of a message. If a message fails due to a temporary error within the SMSC, or during delivery to the carrier, the message is retried automatically and a failure is reported back to the ESME after the SMSC has given up retrying the message.
Final delivery notifications include the following:
- The message was successfully delivered to the phone by the carrier.
- The carrier could not deliver the message to the phone.
- The message delivery failed in the SMSC before, or while attempting to send to the carrier.
Requesting a Delivery Receipt
Delivery Receipts can be requested from the SMSC by setting the registered_delivery parameter in a SubmitSM PDU. The SMSC uses the bits 0,1 and 4 of the registered_delivery parameter as per the Short Message Peer to Peer Protocol (SMPP) 3.4 Specification to determine the types of delivery receipts that will be returned. The supported combinations for the parameter are listed as follows:
x x x 0 x x 0 0
No Delivery Receipts requested.
x x x 0 x x 0 1
Final successful and failure outcome notifications requested.
x x x 0 x x 1 0
Final failure outcomes notifications requested.
x x x 1 x x 0 1
All intermediate and final delivery outcome notifications requested.
If client is interested in receiving delivery receipts, they should set registered_delivery parameter on all parts in case of original long message is split into multiples via User Data Header (UDH).
Parsing a Delivery Receipt PDU
Delivery Receipts are sent back to the ESME via DeliverSM PDUs.
The following parameters are set in Delivery Receipt PDUs:
- The esm_class is set to 4.
- The message_id is set in the receipted_message_id parameter.
- The status of the message is set in message_status. Refer to Sec 5.2.28 in the SMPP 3.4 Specification for the all the possible values. All statuses except ENROUTE are Final Delivery Notifications.
- The short_message is formatted with additional information. Refer to Appendix B in the SMPP 3.4 Specification for more information on the format. Ignore the "ID" field in the short_message because it does not have enough characters to fit the message_id.
Network Specific Error Code
The network specific error code in the short_message will have more information on the cause for the message failure. While Vibes checks to ensure that these errors do not happen prior to transmission, the error codes are included in the following lists for completeness.
Carrier Submission Error Codes (21 - 100)
Carrier submission error codes are errors that occur during the transmission of a message to the carrier. They indicate a failure of the carrier to accept the message for delivery, along with the reason for the failure.
Message content too long.
The maximum message length has been exceeded.
Message failed due to internal bind configuration error.
Contact Vibes Support to check source of configuration error.
Message failed due to internal error while submitting message.
Contact Vibes Support to check cause of the error.
Invalid source address.
For T-Mobile messages, this error is also thrown when we are not able to send messages from a Shortcode to an MDN for the following reasons:
Source address on a blocked list.
Invalid destination address.
The destination Mobile Directory Number (MDN) for the message is invalid, due to the following:
Destination address on a blocked list.
Carrier message queue full.
Exceeded allowed carrier throttle rates.
Carrier failed while delivering message due to temporary error.
Carrier failed while delivering message.
Carrier temporarily unable to route message.
Carrier unable to route message.
Carrier system unavailable.
Destination not opted in to receive messages from source address.
Invalid number of destinations.
Invalid distribution list name.
Invalid submit to distribution list.
Invalid number of messages.
Invalid scheduled delivery time.
Invalid Validity Period value.
MDN not active on the carrier network.
|The MDN is not currently active based on the response code we have received from the carrier. When this error code is received, the MDN should be removed from any Subscription Lists.|
Unknown Error while submitting to the carrier.
Carrier Delivery Receipt Error Codes (100 - 140)
Delivery Receipt error responses indicate the failure of the carrier to deliver a message to the phone.
Carrier returned that the receipt state of the message is Unknown.
Message validity expired before the carrier could deliver to the phone.
Message was deleted by the carrier.
Message was undeliverable by the carrier to the phone.
Message was accepted on behalf of the phone.
Message was rejected by the phone.
The MDN is not opted in for premium/subscription services.
Verizon-specific status when the VMP does not have an opt-in for the MDN. Not a part of the SMPP 3.4 Specification.
Carrier failed while submitting message.
Verizon-specific status. Not a part of the SMPP 3.4 Specification.
A general catch-all error when Vibes is not able to parse the status of the message returned by the carrier.