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:

1. 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.
2. 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:

1. 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.
2. errors: This property includes an object for each error that occurred.
3. 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.