SMS Status Callbacks

The Messages API uses status callbacks to notify your application when the state of a message changes, for example, when it’s sent, delivered, or rejected. These callbacks give visibility into the message lifecycle across all channels, including SMS. This guide explains how SMS delivery receipts (DLRs) are handled and mapped to Messages API status callbacks.

When you send a message using the SMS channel in Messages API, Vonage’s underlying SMS API delivers the message to an operator or provider and reports back with delivery receipts (DLRs). These DLRs describe how far the message progressed through the network. Messages API then translates these SMS DLRs into a standardized set of status callbacks and sends them to your configured webhook URL.

SMS Message Lifecycle

An SMS message typically goes through the following stages:

Stage Description Chargeable Event Messages API Status
Accepted by SMS API The message has been accepted and routed through SMS API gateways. Yes submitted
Delivered to device A delivery receipt (DLR) from the network confirms that the message reached the end-user device. No additional charge delivered
Expired, failed, or rejected The message could not be delivered or was rejected by the SMS API or provider. — rejected

Note: SMS delivery reports can vary in reliability depending on the operator. Some networks may not send DLRs or may report inaccurate statuses.

SMS DLRs vs Messages API Status Callbacks

SMS providers send delivery receipts (DLRs) to indicate message progress. Messages API processes these DLRs and maps them to its own status model.

SMS DLR Status Messages API Status Notes
accepted submitted Sent when SMS API accepts the message for delivery.
buffered (ignored) Rarely used by SMS API; not forwarded.
delivered delivered Indicates receipt by the end-user device (if supported by carrier).
expired rejected Maps to internal error code 1360.
failed rejected Indicates provider failure or network error.
unknown rejected Maps to internal error code 1330.
rejected rejected Maps according to MMS/SMS Error Code Mappings.

Example: SMS Status Callback

When an SMS message is successfully accepted by the SMS API, you’ll receive a submitted callback similar to this:

{ 
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab", 
  "to": "447700900000", 
  "from": "447700900001", 
  "timestamp": "2023-05-01T14:00:00.000Z", 
  "status": "submitted", 
  "usage": { 
    "currency": "EUR", 
    "price": "0.0333" 
  }, 
  "client_ref": "string", 
  "channel": "sms", 
  "destination": { 
    "network_code": "12345" 
  }, 
  "sms": { 
    "total_count": "2" 
  } 
}

If a DLR later confirms delivery, another callback will follow with "status": "delivered".

Further Information