Webhooks – Delivery Receipts

Delivery Receipts

Upon a successful delivery of the SMS, or in the event that it is not possible to deliver the SMS for some reason, then a Delivery Receipt will be posted to a Webhook address. This Webhook address can be set up in the user dashboard as part of the configuration of the API Keys that you set up to access the API. Alternatively, this Webhook address can be overridden on a message by message basis by populating the "custom_callback_url" field of the "delivery_receipts" element of the SMS submission request.

The delivery receipt can arrive any time after the message was submitted, up to 24 hours later. The delivery receipt Webhook should be acknowledged with an HTTP 200 OK response. If the delivery receipt is unable to connect to the Webhook address or if a non HTTP 200 OK response is received, it will be queued and re-tried for up to 24 hours before being discarded.

If the client provides a "client_reference" in the Submit SMS request, the same will be passed to them in the DLR callback.

The Webhook call will be sent as a POST with a JSON document in the request body. It will be of the following format:

{
  "message_id": "...the message id returned in the Submit SMS API request...",
  "sender_address": "...sender address...",
  "destination_address": "...destination phone number...",
  "status": "DELIVRD",
  "error_code": 0,
  "smsc_timestamp": "yyyy/mm/dd hh:mm:ss"
  "client_reference": "...if provided during original request..."
}

Status Values List

Status	Final State	Description
DELIVRD	Yes	Message successfully delivered
EXPIRED	Yes	Delivery failed and the network will no longer retry
DELETED	Yes	The delivery of this message was aborted at some point in the network
UNDELIV	Yes	The message was aborted within the network as it could not be delivered for some reason.
REJECTD	Yes	The message was rejected before submitting to the network because it did not meet suitable criteria for delivery.
ENROUTE	No	Message has been accepted by the next hop in the network, but it has not yet been delivered to the handset.
UNKNOWN	Yes	Message delivery outcome is unknown, an unsupported event was received from the network.
SUBMITTED	No	Message has been accepted and acknowledged by the next hop on the network, but we have not yet received a status value for it.
ACCEPTD	No	Message has been accepted by the next hop in the network, but it has not yet been delivered to the handset.