Delivery Reports

The SMS API can send delivery reports to your application through a callback URL.

You can configure the callback URL on your SMS API application.

Configure the callback

Set your application's Delivery Reports Callback URL to an endpoint that accepts HTTP POST requests.

For example:

https://example.com/webhooks/sms/delivery-status

If no callback URL is configured, delivery reports are still processed normally but no callback is sent to your application.

Callback request

Delivery reports are sent as an HTTP POST request with a JSON body.

POST https://example.com/webhooks/sms/delivery-status
Content-Type: application/json

The request body looks like this:

{
  "batch_id": "20bc680b-974d-4f33-affa-273414ebb77f",
  "mobile": "254701234567",
  "dlr": {
    "description": "DeliveredToTerminal",
    "timestamp": "1757592000"
  }
}

Callback fields

Batch ID

The batch_id is returned when the SMS request is successfully queued.

Use it to associate delivery reports with the original SMS request.

For example:

SMS request
    ↓
batch_id: 20bc680b-974d-4f33-affa-273414ebb77f
    ↓
Delivery report
    ↓
batch_id: 20bc680b-974d-4f33-affa-273414ebb77f

Callback response

Your callback endpoint should return any HTTP 2xx response when the delivery report has been received successfully.

For example:

HTTP/1.1 200 OK

Any 2xx response is treated as a successful callback.

Callback timeout

The API waits up to 10 seconds for your callback endpoint to respond.

Your endpoint should process the delivery report and return a response as quickly as possible.

Callback failures

If your callback endpoint fails or does not respond successfully, this does not affect the processing of the delivery report.

The delivery report processing continues independently of the callback result.

Example webhook handler

A basic webhook endpoint might receive the request as follows:

{
  "batch_id": "20bc680b-974d-4f33-affa-273414ebb77f",
  "mobile": "254701234567",
  "dlr": {
    "description": "DeliveredToTerminal",
    "timestamp": "1757592000"
  }
}

Your application can then use the batch_id and mobile to update the delivery status of the corresponding SMS.

Important

The delivery report does not contain the provider's internal message ID.

Use the batch_id together with the recipient mobile number to associate the report with your original SMS request.