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.

ParameterTypeDescriptionExampleRequired?
statusobjectContains properties related to the request status.
status.updated_onstringAn RFC 3339 timestamp indicating when the delivery status was last updated.2020-08-27T17:28:49.559307Z
status.codeintegerA numeric code indicating the status of the transaction.200
status.descriptionstringText describing the delivery status of the transaction.Delivered to handset
submit_timestampstringAn ISO 8601 UTC timestamp indicating when the request was received.2016-01-01T01:01:01.010101Z
errorsarray of objectsContains an object for each error that occurs, describing that error.
errors.{}objectContains properties related to an error that occurred during processing of the request.
errors.{}.codeintegerA numeric code specifying which error occurred.-10001
errors.{}.descriptionstringText describing the error that occurred.Invalid Request: PhoneNumber Parameter
reference_idstringA 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.


Did this page help you?