Delivery Status
A common source of confusion is what a success: true send response actually means.
Two kinds of “delivered”
| Signal | Meaning | Guarantee |
|---|---|---|
Send response status: "Success" | The provider accepted the message for delivery | No — it can still fail downstream |
sms.delivered webhook | The message reached (or otherwise left) the carrier in a non-failure state | The authoritative terminal signal |
status: "sent" / "Success" in a send or log response means Africa’s Talking accepted the message onto its routes. The handset may still not receive it — invalid destination, blacklisted subscriber, expired message, or carrier rejection all happen after acceptance.
Message lifecycle
The GET /v1/sms/logs status field moves through:
pending— queued, no report yetsent— accepted by the upstream providerdelivered— carrier confirmed delivery to the handsetfailed— message was definitively not delivered
Only webhooks give you the terminal delivered/failed states reliably and in real time. Our webhook system maps the provider’s delivery reports into normalized sms.delivered / sms.failed events delivered to your HTTPS endpoint with signature verification and retries.
Read delivery reactively
- Send a message and store the
message_idreturned in the response. - Register a webhook endpoint (see Webhooks).
- When an event arrives, correlate it back to your records using
message_idandto. - Update your order/notification state only on
sms.delivered, and surface a failure path onsms.failed.
Credits still count on failure
A message that fails after acceptance is refunded per the provider reconciliation. Bulk responses report and refund partial failures individually. If a recipient fails in a bulk batch, that recipient’s credits_used is not billed — the item carries an error instead.
Never gate a user-visible outcome (refunds, order fulfillment) on the send response. Gate it on the webhook.