Call recordings

This section describes the REST API for call recordings. Use it to list, play, download, and delete the recordings of a specific call on VoiceAI Connect. The Session Recording Server (SRS) records calls through SIPREC, and VoiceAI Connect converts each recording to a stereo WAV file, with one side of the call on each channel.

The feature is applicable only to VoiceAI Connect Enterprise Version 3.26.4 and later.

The feature is applicable only when the AudioCodes SRS is used.

The REST API for call recordings is done over HTTPS and supports the following HTTPS method requests:

The REST API for call recordings requests is made from the REST client to VoiceAI Connect (server), using the resource URI /api/v1/recordings/. The REST requests can be done on the following REST resources:

REST Resource

HTTP Request

Description

/api/v1/recordings/{cdrId}

GET, DELETE

Lists the recordings of the call, or deletes all of them.

/api/v1/recordings/{cdrId}/files/{recordingId}

DELETE

Deletes a specific recording of the call.

/api/v1/recordings/{cdrId}/files/{recordingId}/download

GET

Downloads a specific recording as a WAV file.

/api/v1/recordings/{cdrId}/files/{recordingId}/play

GET

Streams a specific recording for playback.

/api/v1/recordings/{cdrId}/files/{recordingId}/samples

GET

Retrieves the waveform samples of a specific recording.

This feature is applicable only to VoiceAI Connect Enterprise with call recording (SIPREC) deployed. If call recording isn't deployed, every call recording request returns 404.

VoiceAI Connect keeps recordings for the retention period of the account (by default, 30 days), and then deletes them automatically. The first play or download of a recording can take a few seconds, while VoiceAI Connect retrieves and converts it. Calls that failed or have a duration of zero have no recordings.

All call recording requests, including the DELETE requests, require the VAIC/CALLS/READ role. VoiceAI Connect records each download and deletion in the Activity Log.

In addition to the responses listed for each request, any call recording request can return one of the following HTTP status codes:

HTTP Status Codes

Description

400 Bad Request

A parameter failed validation, or the recording ID is malformed.

500 Internal Server Error

An unexpected internal error occurred in VoiceAI Connect.

502 Bad Gateway

The recordings service rejected the credentials of VoiceAI Connect, or the audio stream failed before any data was sent.

503 Service Unavailable

The recordings service can't be reached, timed out, or returned another error (for example, a 5xx status code).

Error responses have a JSON body with the statusCode, message, and error fields. Authentication and permission errors (401 and 403) have a JSON body with the statusCode, message, and timestamp fields instead.

GET /api/v1/recordings/{cdrId}

Description

Retrieves the list of recordings of a specific call (cdrId). Use the recording IDs in the response with the other call recording requests. The recording IDs are available only from this request. The durationSeconds field of each recording is calculated from its endTime minus its startTime.

Path Parameters

Parameter

Type

Description

cdrId

String

The ID of the call's record (CDR), as shown in Call History. A call can have more than one recording.

1 to 128 characters: letters, digits, and the characters _ . : -.
Request Body

None

Authentication

To use this API, define the application with the following policy:

Role: VAIC/CALLS/READ

For more information on assigning policies (roles and scopes) to users and applications, see Manage users.

Responses

Can return the following responses:

Response Example
[
  {
    "recordingId": "20260809_20260809-142035.011_..._386a78b28fff1f97_0",
    "startTime": "2026-08-09T14:20:35.011Z",
    "endTime": "2026-08-09T14:23:10.400Z",
    "durationSeconds": 155.389
  }
]

GET /api/v1/recordings/{cdrId}/files/{recordingId}/download

Description

Downloads a specific recording (recordingId) of a call as a stereo WAV file, which you can play in any media player. The response has the Content-Disposition: attachment header. VoiceAI Connect records each download in the Activity Log.

To download all recordings of a call, send one request per recording. To record the whole batch as one Activity Log entry, add the batchSize and batchLead query parameters to each request.

Path Parameters

Parameter

Type

Description

cdrId

String

The ID of the call's record (CDR), as shown in Call History. A call can have more than one recording.

1 to 128 characters: letters, digits, and the characters _ . : -.

recordingId

String

The ID of one recording of the call. To get the IDs, use GET /api/v1/recordings/{cdrId}.

1 to 256 characters: letters, digits, and the characters _ . -.
Query Parameters

Parameter

Type

Description

batchSize

Integer

(Optional) The number of recordings in the "download all" batch. A value less than 2 is handled as a single download.

batchLead

Boolean

(Optional) Set to true on the one request in the batch that writes the Activity Log entry, and to false on the other requests.
Request Body

None

Authentication

To use this API, define the application with the following policy:

Role: VAIC/CALLS/READ

For more information on assigning policies (roles and scopes) to users and applications, see Manage users.

Responses

Can return the following responses:

For example, the following curl command downloads a recording and saves it as recording.wav:

curl -H "Authorization: Bearer ACCESS_TOKEN" \
  -o recording.wav \
  "https://VAIC_HOST/api/v1/recordings/CDR_ID/files/RECORDING_ID/download"

GET /api/v1/recordings/{cdrId}/files/{recordingId}/play

Description

Streams a specific recording (recordingId) of a call for playback, for example, in an HTML audio element. The response has the Content-Disposition: inline header. The optional range header lets the player request part of the recording, so it can seek without downloading the whole file.

To save the recording as a file, use the download request instead.

Path Parameters

Parameter

Type

Description

cdrId

String

The ID of the call's record (CDR), as shown in Call History. A call can have more than one recording.

1 to 128 characters: letters, digits, and the characters _ . : -.

recordingId

String

The ID of one recording of the call. To get the IDs, use GET /api/v1/recordings/{cdrId}.

1 to 256 characters: letters, digits, and the characters _ . -.
Request Headers

Header

Type

Description

range

String

(Optional) The byte range of the recording to return, in the standard HTTP Range format, for seeking. For example, bytes=0-1023 returns the first 1,024 bytes. If you omit this header, the whole recording is returned. Media players send this header automatically.
Request Body

None

Authentication

To use this API, define the application with the following policy:

Role: VAIC/CALLS/READ

For more information on assigning policies (roles and scopes) to users and applications, see Manage users.

Responses

Can return the following responses:

GET /api/v1/recordings/{cdrId}/files/{recordingId}/samples

Description

Retrieves audio samples of a specific recording (recordingId) of a call, for drawing the waveform of each side of the call. The VoiceAI Connect web interface uses these samples in the Recordings window.

Path Parameters

Parameter

Type

Description

cdrId

String

The ID of the call's record (CDR), as shown in Call History. A call can have more than one recording.

1 to 128 characters: letters, digits, and the characters _ . : -.

recordingId

String

The ID of one recording of the call. To get the IDs, use GET /api/v1/recordings/{cdrId}.

1 to 256 characters: letters, digits, and the characters _ . -.
Query Parameters

Parameter

Type

Description

resolutionMs

Integer

(Optional) The time between samples, in milliseconds. The minimum is 10.

maxSamples

Integer

(Optional) The maximum number of samples per channel. To stay under this limit, VoiceAI Connect increases the time between samples.
Request Body

None

Authentication

To use this API, define the application with the following policy:

Role: VAIC/CALLS/READ

For more information on assigning policies (roles and scopes) to users and applications, see Manage users.

Responses

Can return the following responses:

Response Example
{
  "requestedResolutionSeconds": 0.1,
  "actualResolutionSeconds": 0.2,
  "maxSamples": 1000,
  "durationSeconds": 155.4,
  "channels": [
    {
      "channel": 0,
      "waveform": [
        0.01,
        0.12,
        0.34
      ]
    }
  ]
}

The resolution fields in the response (requestedResolutionSeconds and actualResolutionSeconds) are in seconds, although the resolutionMs query parameter is in milliseconds. A maxSamples value of 0 in the response means that there's no limit.

DELETE /api/v1/recordings/{cdrId}/files/{recordingId}

Description

Permanently deletes a specific recording (recordingId) of a call. The other recordings of the call aren't affected. VoiceAI Connect records each deletion in the Activity Log.

Path Parameters

Parameter

Type

Description

cdrId

String

The ID of the call's record (CDR), as shown in Call History. A call can have more than one recording.

1 to 128 characters: letters, digits, and the characters _ . : -.

recordingId

String

The ID of one recording of the call. To get the IDs, use GET /api/v1/recordings/{cdrId}.

1 to 256 characters: letters, digits, and the characters _ . -.
Request Body

None

Authentication

To use this API, define the application with the following policy:

Role: VAIC/CALLS/READ

For more information on assigning policies (roles and scopes) to users and applications, see Manage users.

Responses

Can return the following responses:

You can't restore a deleted recording.

DELETE /api/v1/recordings/{cdrId}

Description

Permanently deletes all recordings of a specific call (cdrId) at once. VoiceAI Connect records each deletion in the Activity Log.

Path Parameters

Parameter

Type

Description

cdrId

String

The ID of the call's record (CDR), as shown in Call History. A call can have more than one recording.

1 to 128 characters: letters, digits, and the characters _ . : -.
Request Body

None

Authentication

To use this API, define the application with the following policy:

Role: VAIC/CALLS/READ

For more information on assigning policies (roles and scopes) to users and applications, see Manage users.

Responses

Can return the following responses:

You can't restore deleted recordings.