SMS - Callback service

This page explains how to understand the callbacks you receive that are related to a Telesign SMS transaction (excluding bulk SMS 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.

Before you begin

Ensure you have the following set up:

• Integration with SMS - You will only receive these callbacks if you've made a Telesign SMS request. See our SMS Tutorials 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 Receive SMS delivery reports 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": "sms",
  "additional_info": {
    "mcc": "310",
    "mnc": "004",
    "price": "0.01",
    "currency": "USD",
    "message_parts_count": "2",
    "message_parts_reference_ids": "35E63E88CB000E049196AD1CFCFFB89C,35E63E88CC7C050491613443467F3F12"
  },
  "reference_id": "0123456789ABCDEF0123456789ABCDEF"
}

Here are a few important things to understand about this notification:

1. additional_info - This property is only included if at least one optional feature is enabled. Each of its sub-properties is only included if the relevant optional feature is also enabled. Contact Telesign Customer Support to request enablement of new features. Some features are for full-service accounts only.

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": "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 SMS are included on the Receive SMS delivery reports 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 "SMS" on the All Status and Error Codes page.