Bulk SMS API - Track Delivery Status
This page explains how to understand the callbacks you receive that are related to your Bulk SMS API transactions.
NOTE
When you send a message using a Telesign API, you get an initial HTTP response that just indicates the initial processing status of the transaction. A successful response means that Telesign accepted your transaction and will attempt to deliver it.
For further updates on the delivery status of your transaction, including the final delivery status, you receive Transaction Callback Notifications.
After you have completed the general setup steps for your Transaction Callback Service, review the following additional details specific to Bulk SMS API callbacks.
Reference
The full schema for these callbacks can be found on the Bulk SMS Callbacks reference page.
Examples
Success
POST /callback_endpoint HTTP/1.1
Host: your-callback-url.com
{
"status": {
"updated_on": "Thu, 23 Jun 2022 19:03:44 GMT",
"code": 200,
"description": "Delivered to handset"
},
"errors": [],
"sub_resource": "bulk_sms",
"session_id": "255E3E34382C0E049046BF14FF7F3435",
"reference_id": "0123456789ABCDEF0123456789ABCDEF"
}
Here are a few important things to understand about this response:
- session_id: The meaning of this property differs depending on the structure of your original request.
- If you included an ID for this recipient in the request, the value echoes this ID.
- If you did not provide an ID for this recipient, but you did provide your own overall transaction ID in the
session_id
request parameter, that value is present for this property instead. - If you provided neither, the value of this property is
null
.
- reference_id: This identifies which of your Bulk SMS API transactions this callback is related to. This is the index to use when searching for Delivery Reports for a given request.
CAUTION
Although it is possible to send messages using this API without tying each phone number to an ID, we strongly recommend generating IDs so you can track the status of each send.
Failure
POST /callback_endpoint HTTP/1.1
Host: your-callback-url.com
{
"status": {
"updated_on": "2022-06-23T19:03:44.420798Z",
"code": 230,
"description": "Message blocked by TeleSign"
},
"errors": [
{
"code": -40025,
"description": "Message blocked by TeleSign"
}
],
"sub_resource": "bulk_sms"
}
Here are a few important things to understand about this response:
- status.code: This property is returned for both success and failure states, and indicates at a high-level what happened. Possible status codes for this API are included on the Bulk SMS Callbacks reference page.
- errors: This property includes an object for each error that occurred.
- errors[0].code: This property indicates which specific error occurred. Possible error codes for this API are labeled as "All" or "Bulk SMS API" on the All Status and Error Codes page.
Updated 8 days ago