SMS Delivery States¶
As an SMS is being processed, it will be in various states. Some of those states are intermediate and some are final.
The diagram below provides an overview of the various states, and how the SMS can change state between them. The intermediate states are all symbolized with round box, and final states with rectangular boxes. The SMS starts out with the placeholder status UNKNOWN when we receive the SMS but when start processing it will quickly gain other states. Once a final state is reached, we will no longer emit any status notifications for the SMS.
The usual path for message state goes is Buffered, Enroute, Delivered. Although many providers will skip some status, such as Buffered, which is rarely seen as the messages often goes directly to routing which instead emits the status Enroute.
Undelivered and Rejected are also fairly common states, these indicate that the SMS could not be delivered to the recipient. This can be because of problems with the SMS such as the recipient MSISDN not being in active use or perhaps country specific restrictions.
We try to deliver DSNs in a logical order, but they may not always arrive at your webhook in order and sometimes you may receive a transient state after already having received a final state. In this case you should ignore the transient state.
|UNKNOWN||No||Initial value for before processing begins, waiting for actual status.|
|SCHEDULED||No||Used for messages where you set a sendtime in the future.|
|BUFFERED||No||The message is held in our internal queue and awaits delivery to the mobile network.|
|ENROUTE||No||Message has been sent to mobile network, and is on its way to its final destination.|
|DELIVERED||Yes||The end users mobile device has confirmed the delivery, and if message is charged the charge was successful.|
|EXPIRED||Yes||Message has exceeded its validity period without getting a delivery confirmation. No further delivery attempts.|
|DELETED||Yes||Message was canceled.|
|UNDELIVERABLE||Yes||Message is permanently undeliverable. Most likely an invalid MSISDN.|
|ACCEPTED||Yes||The mobile network has accepted the message on the end users behalf.|
|REJECTED||Yes||The mobile network has rejected the message. If this message was charged, the charge has failed.|
|SKIPPED||Yes||The message was accepted, but was deliberately ignored due to network-specific rules.|
Depending on how the SMS is received by our systems the delivery notification will take on different forms.
Of course the status is also available to be seen in the SMS trafic log.
In addition to the regular SMS state, when sending overcharged SMSes each SMS will also have a charge status. Just like the regular status, the initial value is a placeholder, for the charge status the placeholder is NOCHARGE.
The REFUND_FAIL state is just a notification, the actual state will still be CAPTURED.
The normal flow will go from AUTHORIZED to either FAILED or CAPTURED.
|NOCHARGE||Initial value for before processing begins. Waiting for actual status.|
|AUTHORIZED||The transaction is authorized|
|CANCELLED||The transaction is cancelled or timed out|
|CAPTURED||The transaction is captured and the amount will be charged from the recipients phone bill|
|FAILED||The transaction failed. Usually because the phone number has blocked for overcharged SMS|
|REFUNDED||A previously captured transaction has been successfully refunded to the phone owner|
|REFUND_FAIL||The refund procedure failed.|
Overcharged SMS is only implemented in the REST API.