SMS Verify API - Callback service

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

📘

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 Verify API - You will only receive these callbacks if you've made a Telesign SMS Verify API request. See SMS Verify API - Verify with your own code or SMS Verify API - Verify with Telesign code 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 SMS Verify Callbacks reference page.

Examples

Success

POST /callback_endpoint HTTP/1.1
Host: your-callback-url.com
{
  "status": {
    "code": 200,
    "description": "Delivered to handset",
    "updated_on": "2016-10-21T14:05:36.181346Z"
  },
  "submit_timestamp": "2016-01-01T01:01:01.010101Z",
  "errors": [],
  "reference_id": "B56259E45884010488343BAA15FB0002",
  "verify": {
    "code_state": "UNKNOWN",
    "code_entered": null
  },
  "sub_resource": "sms",
  "additional_info": {
    "message_parts_count": 2,
    "price": "0.5112",
    "mnc": "004",
    "mcc": "310",
    "currency": "USD",
    "message_parts_reference_ids": "35E63E88CB000E049196AD1CFCFFB89C,35E63E88CC7C050491613443467F3F12"
  }
}

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