Call Recording Retrieval API Reference

TeleSign’s Call Recording API allows you to retrieve details about call recordings you set up.

NOTE:

If you are looking for commands to start, stop, pause, or resume a recording, you should review the Customer Action API.

General Information

All requests submitted for this API:

  • Must be authenticated with basic authentication.
  • Use https://rest-ww.telesign.com/v2/call_recording as the base endpoint.
  • Use Content-Type application/json.
  • Accept only UTF-8 encoded unicode characters as inputs.

This API is used with the Customer Action API and the Voice API if you want to be able to retrieve call recordings.

Call Recording API Structure

TeleSign’s Call Recording API is used to retrieve information about recordings you set up. If you want to set up a recording, you would use the Voice API and the Customer Action API.

Retrieve a List of Recordings By Reference ID

To retrieve a list of recordings, you send a GET request to https://rest-ww.telesign.com/v2/call_recording/{reference_id}.

Request for List of Recordings
GET https://rest-ww.telesign.com/v2/call_recording/{reference_id} 
Content-Type: application/json
Authorization: Basic base64encodedtoken

The reference_id you provide is for a specific call. The Call Recording API will then return a list of recordings (if they exist). Multiple files are returned in the situation where someone starts and stops the recording several times during a call.

The response body comes back like this:

Response Body for Call Recording for a Single Call
[
  {
    "reference_id": "D596D7B0D1800164898350B4E71B005C",
    "file_name": "the title of the recording",
    "status": "available",
    "date": "UTC formatted date",
    "url": "URL to retrieve call recording"
  }
]
Call Recording Response
object
reference_id
string

A unique identifier that you can use to retrieve information about a call.

file_name
string

The name of a recorded file.

status
string

The status of the recording. Choices include -

  • recording - the call recording is in progress (there will not be a file name or URL provided if it is in this status)
  • available - the call recording is complete and available for retrieval
  • deleted - you or someone deleted the recording
date
string

The UTC formatted date when the recording was created. It will look like this: YYYY-mm-ddTHH:MM:SS.

url
string

The link to the call recording so you can retrieve and listen to it.

Retrieve a List of Calls By Date Range

To retrieve a list of recordings by date range, you send a GET request including your date range to https://rest-ww.telesign.com/v2/call_recording?start_date_time=2019-04-01T03:00:00&end_date_time=2019-04-02T23:00:00. It will return a list of all recorded calls in the specified time range. From the list, you can then choose the appropriate call and use the associated reference ID to retrieve recordings.

Query Parameter Example Description
start_date_time 2019-04-01T03:00:00 start date range
end_date_time 2019-04-02T23:00:00 end date range
pagesize 10 This represents the number of rows you want to return per page. The maximum allowed per page is 100.
token -add- If you reach a certain number of recordings in a list, you can continue to the other pages if you’ve provided the token in your request.

Here is an example request:

Request for List of Recordings by Date Range
GET https://rest-ww.telesign.com/v2/call_recording?start_date_time=2019-04-01T03:00:00&end_date_time=2019-04-02T23:00:00
Content-Type: application/json
Authorization: Basic base64encodedtoken

The response body comes back like this, with one set of these four parameters per recording found:

Call Recording Retrieval by Date Range Response Body
{
    "call_recordings": [
        {
            "reference_id": "D596D7B0D1800164898350B4E71B005C",
            "date": "UTC formatted date",
            "status": "available",
            "file_name": "my recording"
        },
        ...
    ],
    "token": "Z0FBQUFBQmRTM01KYUtpQUlRc0FNcEpuMjczYmlZcC1CMlZVeTlDWjU2a3NvdlRoRUlhVG5jVXlZTUZhcFNqcWd1QjY5eUd2U3FaM1d2LWY1WUl3RURxQ0dieWFaNTZ5MHdQd2N2WnFnRTFzNkw5eXNhZEdYbFNmck84QnRwUXNhUFMzVFl1alNLYy1KOF85MTZXRnpxZXhJTWQ1MGtzR0dvOVpiTWZlTnBVeEQ2RlpNNFAzLTdnNk5iNXJmdkJic3NoemlfZmZfR3JKYTM2eE1QZ1lZU0d4YldZWWJiQ0NTdG0xU1RJaU5hYU5zZjl2VVNXTWVRX1VPWFZFTjZFc1QyY2dHU3d1TElsMUNNZkxob3NrUU85SHUxbHEzaXBTVFZHVVMwYU9oS2tKR1BmQWtVYUJQZmNBdGhmelltbEJfZUt3S3U3ek1QU3BuTjY0cXkzNmdKd3lWTzQ2MHdVdW1NOVNTaWZ0SmJMZ0lqaklSajlTbVpEZUFzbFVqRExkUmlVb0IyeFdPVlRT"
}
Call Recording Response Parameters
object
file_name
string

The name of the file for the recording.

status
string

The status of the recording. Choices include -

  • recording - the call recording is in progress (there will not be a file name or URL provided if it is in this status)
  • available - the call recording is complete and available for retrieval
  • deleted - you or someone deleted the recording
date
string

The date uses the following format: YYYY-mm-ddTHH:MM:SS.

reference_id
string

The reference ID that comes back

Delete Recordings By Reference ID

If you wish to delete recordings for a particular call, send the reference ID for the call in a request to https://rest-ww.telesign.com/call_recording/{reference_id}.

Delete Recordings for a Call Request
DELETE https://rest-ww.telesign.com/v2/call_recording/{reference_id}
Content-Type: application/json
Authorization: Basic base64encodedtoken

Status Codes

The Call Recording Retrieval API returns one of the following HTTP responses:

Name Description
200 OK Includes all call recording information in the response.
204 No Content When you send a DELETE request, you will always get this response unless something goes wrong.
400 Bad Request Your request contains invalid parameters or is missing parameters. Some things to check are the start_date_time and end_date_time - make sure you use the proper UTC format. It may also be because you did not include a required token that was returned from a previous query. (The token is required when you want to get results past the first page of recordings. You must send an additional request containing the token.)
401 Unauthorized Credentials are not valid or they were not provided at all.
404 Not Found You can receive a 404 if no call recordings are found.