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.

Parameter

Type

Description

Example

Required?

status

object

Contains properties related to the request status.

status.updated_on

string

An RFC 3339 timestamp indicating when the delivery status was last updated.

2020-08-27T17:28:49.559307Z

status.code

integer

A numeric code indicating the status of the transaction.

200

status.description

string

Text describing the delivery status of the transaction.

Delivered to handset

submit_timestamp

string

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

2016-01-01T01:01:01.010101Z

errors

array of objects

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

errors.{}

object

Contains properties related to an error that occurred during processing of the request.

errors.{}.code

integer

A numeric code specifying which error occurred.

-10001

errors.{}.description

string

Text describing the error that occurred.

Invalid Request: PhoneNumber Parameter

reference_id

string

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

35C8B5D509BC10689196FED2AD551B8A

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

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.

561561

Did this page help you?