Transaction Callback Service

This page explains how to set up and use a Transaction Callback Service to receive status updates about your requests to some TeleSign services. This architecture is only supported for the Messaging API, SMS API, SMS Verify API, Voice API, Voice Verify API, and Inbound SMS service.

Key Features

  • Controlled by You: This is a web service that you set up and control.
  • Compound Queries: Unlike the Get Status API, a Transaction Callback Service can be used to learn the status of multiple transactions at the same time.
  • Efficient: Makes more efficient use of network system resources (for example, bandwidth or server load) when making compound queries. This may be a significant advantage if you have a high volume of transactions.

Service Setup

  1. Create a web service with a private URL for receiving callback notifications from TeleSign. Notifications are sent as web requests to this service.

General Requirements

  • Base URL: Any URL that you control.
  • Protocols: https
  • Ports: 443 (The default standard port for HTTPS)
  • Authentication: Authentication is optional, but recommended. TeleSign sends callbacks with headers that can be used for Digest authentication. See Authenticated Callbacks With the Transaction Callback Service for more details.
  • Accepts: application/json
  • Responds With: application/json
NOTE:

For mission-critical applications, TeleSign recommends that you provide redundancy by implementing two URLs instead of one.

Request Body

Note that the schema for a callback varies depending on which TeleSign service it comes from. Below is the general schema; the documentation for each product explains any variations from this schema.

object
status
object

Contains properties related to the request status.

required
submit_timestamp
string

An ISO 8601 UTC timestamp indicating when the request was received.

1 validation + required
errors
array[object]

Contains an object for each error that occurs, describing that error.

reference_id
string

A unique, 32-digit hex value randomly generated by TeleSign to identify this request.

1 validation + required

Example Notification

This example is for an SMS Verify transaction. Product-specific parameters that are not part of the general schema are highlighted in the code.

Example Callback Notification
HTTPS
POST /callback_endpoint HTTP/1.1
Host: your-callback-url.com
{ 
  "status": { 
     "updated_on": "2016-07-08T20:52:46.417428Z", 
     "code": 200,
     description": "Delivered to handset" 
   }, 
   "submit_timestamp": "2016-07-08T20:52:41.203000Z", 
   "errors": [], 
   "verify": { 
     "code_state": "VALID", 
     "code_entered": null 
   }, 
   "sub_resource": "sms", 
   "reference_id": "2557312299CC1304904080F4BE17BFB4" 
}
  1. Provide TeleSign with your private URI.
  2. Allow one business day for setup to be completed.
  3. You will receive callback notifications after both of the following occur:
    • A transaction completes.
    • TeleSign determines the final status of the transaction (refer to the section Transaction Status Codes on the Codes, Languages, and Timezones page for a list of status codes that may be returned).
  4. If TeleSign is unable to deliver your callback notification on the first attempt, the TeleSign server tries again. If the second attempt fails, the server makes a third and final attempt.

Here is a diagram of what the notification flow looks like, using SMS Verify for the example. The flow is similar for other products.