Call Recording Retrieval API - Download Recordings

This page walks you step-by-step through how to use the Call Recording Retrieval API to retrieve all call recordings within a date range.

Keep the following reference pages open in another window while you work on these steps:

Step 1: Get List of Call Recordings by Date Range

  1. Send a POST /v2/call_recording request to the Call Recording Retrieval API. Include the following query param values:
ParameterValueDescriptionRequired?
start_date_timeA timestamp in {YYYY}-{MM}-{DD}T{hh}:{mm}:{ss} format.The date-time defining the beginning of the date range (inclusive).yes
end_date_timeA timestamp in {YYYY}-{MM}-{DD}T{hh}:{mm}:{ss} format.The date-time defining the end of the date range (inclusive).yes

Request

GET /v2/call_recording?start_date_time=2019-04-01T03:00:00&end_date_time=2019-04-02T23:00:00 HTTP/1.1
Host: rest-ww.telesign.com

You should get a response that looks like this:

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
  "call_recordings": [
    {
      "reference_id": "D596D7B0D1800164898350B4E71B005B",
      "file_name": "D596D7B0D1800164898350B4E71B005B_1631039233.wav",
      "status": "available",
      "date": "2021-09-07T18:27:24"
    },
    ...
  ],
  "token": "Z0FBQUFBQmRTM01KYUtpQUlRc0FNcEpuMjczYmlZcC1CMlZVe"
}

📘

NOTE

... is used above to abbreviate a series of many objects. In a real response, all results appear unabbreviated.

This response provides the first page of results.
The array for the call_recordings property contains one object for each call recording that falls within your date range, up to the pagination limit. Save the value of the token property.

  1. To get the next page of results, make another POST /v2/call_recording request. This time for query string parameters, only include the token from the earlier response.

Request

GET /v2/call_recording?token=Z0FBQUFBQmRTM01KYUtpQUlRc0FNcEpu HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Host: rest-ww.telesign.com

The response includes the next page of results. Continue making requests until you've retrieved all the results for the date range. You'll know you've reached the end of the results when the token property returns with a value of null.

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
  "call_recordings": [
    {
      "reference_id": "D596D7B0D1800164898350B4E71B006F",
      "file_name": "D596D7B0D1800164898350B4E71B006F_1631039299.wav",
      "status": "available",
      "date": "2021-09-07T18:27:24"
    }
  ],
  "token": null
}

Save the value of call_recordings[n].reference_id for each call recording.

Step 2: Get Call Recordings by ID

  1. Send a POST /v2/call_recording/{reference_id} request to the Call Recording Retrieval API. Include the following path param values:
ParameterValueDescriptionRequired?
reference_idThe first call_recordings[n].reference_id value you saved in the previous step.Specifies the call for which you want to retrieve or delete recordings.yes

Request

GET /v2/call_recording/D596D7B0D1800164898350B4E71B005B HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Host: rest-ww.telesign.com

You should get a response that looks like this:

Response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[
  {
    "reference_id": "D596D7B0D1800164898350B4E71B005B",
    "file_name": "D596D7B0D1800164898350B4E71B005B_1631039233.wav",
    "status": "available",
    "date": "2021-09-07T18:27:24",
    "url": "https://call-recording-stg.tlsn.io/call_recording/D5EF060E544801648584F2ADB26F0184_1631039244.wav?Expires=1631043688&Signature=Jm-Y-qPZMMTbnye-NumQETh~5mNGd6PBRKURKXqeiqj44WeFaKzbdiyXln6ijXff409Srdqme0527mKU15CMuEQXepPeNI64m-ovtt6faE1TbRCa6zHaWeO2dcZM4XYCrILtsgi~j0S5Jj0~PnDMpGXw1XEFOKU55B2o-~asXkxbo-WniO9R8fGV8AHAATwON5roEmxJHNfT1oujq6M3Tq-CNwd46jEhf2tLuVdC1h1XTeHx6UATHPLw3shTPafR3iQ8PP9T8qjWQucoWuAUh5Y7WtDS6U3HMGkOC2QzveHpbA1RNaQMCqT~TvrCtTwEaQr7W~YD82mPwESr9DlRUg__&Key-Pair-Id=APKAJ2B7QX7EM7MEC7SA",
    "transcribe": {
      "language_code": "en-US",
      "transcription": [
        {
          "status": "completed",
          "result": "Welcome to Viatu’s customer service line. To better assist you with your issue, please state your name."
        }
      ]
    }
  }
]

Each object in the array contains info about one call recording file associated with this reference ID.

📘

NOTE

If the recording is stopped and then started again during a call, multiple call recording files are associated with that call's reference ID.

  1. For each object in the array, check that the value of the status property is available.
  2. If the call recording file is available, download it from the URL indicated by the value of the url property.
  3. If the object contains a transcribe property, a transcription was also made for this call recording. To get the transcript, first check that it is ready and available by testing that the transcribe.transcription[0].status property has the value completed.
  4. If the transcript is available, save the value of the transcribe.transcription[0].result property to get the text.
  5. Repeat steps 2-5 above for each object in the array to get each recording file and transcript for this call.

🚧

CAUTION

There may be a delay of up to several seconds between the call recording file being available and the transcript being available.

  1. Repeat all of Step 2 above, but use the next reference ID you've saved, to get recordings for the next call. Continue until you've retrieved recordings for all the calls in your date range.

Did this page help you?