Want to provide feedback?

Write to docs@telesign.com.

Call Query API Reference

TeleSign’s Call Query API is an optional API that you can use with TeleSign’s Voice API and the Customer Action API. It allows you to query TeleSign and find out about calls that occurred in the last three hours. You can also query what calls have been made to a particular phone number within the last ten minutes.

You use this API any time you want information about recently occurring calls. You also use it when you have an incoming call you want to use the Customer Action API to issue actions to. To use that API, you need a reference ID for the call, but to start with, you will not have one for an incoming call. TeleSign’s Call Query API returns a reference ID for a call based on phone number.

General Information

All requests submitted for this API:

  • Must be authenticated with basic authentication.
  • Use https://rest-ww.telesign.com/v2/voice/call as the base endpoint.
    • /incoming/ - allows you to query a call in ‘to number’ and ‘from number’ pairs in the last ten minutes
    • /call/<reference_id> - allows you to retrieve all event information about a call.
  • Are formatted using JSON-RPC.
  • Accept only UTF-8 encoded unicode characters as inputs.
  • You must own the call pointed to by the reference_id parameter in order to query it or do anything to it.

Glossary

  • Call - Connects together two or more parties to allow them to communicate with audio.
  • Events - These are posted by TeleSign to a customer URL you have specified. They occur when you are using the Voice API, unless you choose to disable this feature.
  • Actions - When you want to do something with a call, you use actions to do so. In the Voice API, actions are triggered by events. In the Customer Action API, you can take action on a call without having it triggered by an event. The Call Query API lets you assign a reference ID to an incoming call so you can handle it with the Customer Action API.

Authorization

TeleSign’s Call Query API uses Basic authorization. Whenever you send a request, your header should include an authorization header like this:

Authorization: Basic base64encoded(customer_id:api_key)

In the final version, you would remove the base64encoded and parentheses shown in the example, they are intended to show what part of the content needs to be base64 encoded.

Call Query API Structure

This section describes query requests and responses for the different available endpoints in the Call Query API.

You send queries to assign a reference ID to incoming calls. This reference ID is then referenced for all future API requests regarding the call.

Get a Reference ID for an Incoming Call

The https://rest-ww.telesign.com/call/incoming/<to> endpoint allows you to send a GET request containing a ‘to number’ to find out what calls have been made that include the number in the past ten minutes. Optionally, you can also include a ‘from number’ which will allow you to query for all calls using that phone number pair.

Once you have the reference ID for an incoming call, you can retrieve event information about that call using the https://rest-ww.telesign.com/call/<reference_id> endpoint.

Request

You send a GET request as a query. Your request must contain a ‘to’ phone number (you must own this number to do a query on it), which is presented first. Optionally, you can also include a ‘from’ string, as shown:

GET https://rest.telesign.com/call/incoming/15555551212&from=15555551234

Input Options for Your Query
object
to
string

The phone number that calls are coming to. You must own this phone number to query it.

required
from
string

Optionally, you can include a ‘from’ number. This number allows you to query to and from pairs, narrowing information returned to calls between the specified pair only.

NOTE:

The phone numbers are for the example only.

Response

The response to your query contains information about the latest call that occurred in the last ten minutes.

Response Body
object
reference_id
string

A unique identifier you can use to retrieve information about the latest incoming call to the ‘to’ number you specified.

from
string

The phone number a call is from. If you provided a ‘from’ number in your request, it will be listed here again.

to
string

The phone number incoming calls are going to. You must own this number to do queries.

caller_id
string

The caller ID used to mask the ‘to’ number.

created_on_utc_datetime
string

When the call was created, using UTC format.

answered_on_utc_datetime
string

When the call was answered, using UTC format.

ended_on_utc_datetime
string

When the call ended, using UTC format.

Get Information About a Call

The https://rest-ww.telesign.com/call/<reference_id> end point allows you to send a GET request as a query. This endpoint will return every event for a call associated with the reference ID you provide. Additionally it will return the caller ID used by the ‘to’ number, the call state, when the call was created, answered, and terminated. If you do not have a reference ID for calls to a ‘to’ number you own, you can use the https://rest-ww.telesign.com/call/incoming/<to> endpoint to get a reference ID to use with this endpoint.

You do not need to get a reference ID for an outbound call from the call/incoming endpoint because when you use the Customer Action API to create an outbound call, the asynchronous response you receive will include the reference ID that you can use.

Request

You send a GET request as a query. Your request must include the reference ID for the incoming call you want to query for information about.

Request Parameter
object
reference_id
string

The reference ID for the incoming call you want event information for.

Response

The response to your query will contain all information about the call associated with the reference ID you provided.

Example Response Body
GET /call/B596D7B0D1800164898350B4E71B005C
 
Content-Type: application/json
{
    "reference_id": "B596D7B0D1800164898350B4E71B005C",
    "caller_id": "14645123482",
    "from": "16467740217",
    "to": "16467740229",
    "call_state": "answered",
    "created_on_utc_datetime": "2018-08-07T20:33:38.003718",
    "answered_on_utc_datetime": "2018-08-07T20:33:40.023718",
    "ended_on_utc_datetime": "2018-08-07T20:53:38.009018",
    "events": [
        {
            "event": "incoming_call",
            "reference_id": "B596D7B0D1800164898350B4E71B005C",
            "params": { 
                "from": "12674395109",
                "to": "14645123482",
            }
        },
        {
            "event": "speak_completed",
            "reference_id": "B596D7B0D1800164898350B4E71B005C",
            "params": {
                "from": "12674395109",
                "to": "14645123482",
                "status": "speak_successful",
                "collected_digits": "923"
            }
        },
        {
            "event": "call_completed",
            "reference_id": "B596D7B0D1800164898350B4E71B005C",
            "params": {
                "caller_id": "14645123482",
                "from": "12674395109",
                "to": "14645123482",
                "direction": "outbound",
                "created_on_utc": "2018-08-07T20:33:38.003718",
                "answered_on_utc": "2018-08-07T20:33:40.003718",
                "ended_on_utc": "2018-08-07T20:33:44.003718",
                "status": "hangup",
                "duration": 4
            }
        }
    ]
 
}
object
caller_id
string

The caller ID used to mask the ‘to’ number.

from_number
string

The number an incoming call comes from.

to_number
string

The number an incoming call is connecting to.

created_on_utc_datetime
string

When the call was created, using UTC format.

answered_on_utc_datetime
string

When the call was answered, using UTC format.

ended_on_utc_datetime
string

When the call ended, using UTC format.

call_state
string

The state of the call

events
string

A list of every event that occurred on the call. For details about the kinds of events you can see, see the Voice API Reference page.