Voice - Download recordings

📘

NOTE:

To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.

This page walks you step-by-step through how to retrieve all call recordings within a date range or all call recordings by ID for a specified call. Use Get call recordings by ID to download the recording, or save the transcript text (if one is available).

🚧

CAUTION:

Be sure to familiarize yourself with all relevant privacy (including data retention) and recording laws and regulations for your region and your end-users' countries before retrieving call recordings.

See Voice - Delete Recordings if you accidentally recorded sensitive information during a call and need to delete all call recordings for a specific call.

Before you begin

Make sure you have the following before you start:

• Authentication credentials: Your Customer ID and API Key. If you need help finding these items, go to the support article How do I find my Customer ID and API Key.
• Reference ID associated with the call: To get call recordings by ID, you will need the reference_id associated with the call. Follow the process for Get a list of call recordings by date range to obtain this information.
• Reference pages: Keep the following reference pages open in another window while you work on these steps:
  • Get recordings list by date range
  • Retrieve a list of recordings for a call

Get a list of call recordings by date range

1. Send a POST /v2/call_recording request to retrieve a list of recordings by date range. Include the following query param values:

Your request should look similar to this request:

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 for the first page of results:

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.

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.

2. Save the value of the token property.

3. To get the next page of results, make another POST /v2/call_recording request. This time, for query string parameters, only include the token value from the earlier response that you saved from the token property so that your response includes the next page of results.

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

4. 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 as shown in this example.

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
}

5. Save the value of call_recordings[n].reference_id for each call recording. You will need these values to download each call recording file.

Get call recordings by ID

If you have the call_recordings[n].reference_id for each call, you can get call recordings by ID and then download the call recording files and save transcripts that are available.

1. Send a POST https://rest-ww.telesign.com/v2/call_recording/{reference_id} request. Include the following path param values:

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 Vero-Finto'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.

2. For each object in the array, check that the value of the status property is available.
3. If the call recording file is available, download it from the URL indicated by the value of the url property.
4. 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.
5. If the transcript is available, save the value of the transcribe.transcription[0].result property to get the text.

🚧

CAUTION

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

6. Repeat steps 2-5 above for each object in the array to get each recording file and transcript for this call.

7. Repeat all of the steps 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.