SMS - Track bulk delivery status

This page explains how to understand the callbacks you receive that are related to a bulk SMS transaction using Telesign SMS.

📘

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.

Before you begin

Ensure you have the following set up:

• Integration with Bulk SMS - You will only receive these callbacks if you've made a Bulk SMS request. See SMS - Send bulk SMS to learn how to code that integration.
• Transaction Callback Service - This page assumes you can receive Telesign notifications at a callback service you control. See Transaction callback service to learn how to code that integration.

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 notification:

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 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 Bulk SMS 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 notification:

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 Bulk SMS 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" on the All Status and Error Codes page.