Stream the audio of a recording
GET /v1/recordings/{recording_id}/audio
| Property | Value |
|---|---|
| Operation | stream_recording_audio |
| Group | Recordings |
| Scope | recordings:read |
| Route class | read |
| Idempotency | No Idempotency-Key |
| Audit | An audited content read recording.audio.read |
| Released in | 1.15.0 |
| Phase 0 host | Served (the hosted api pins 1.65.0) |
Answers audio/wav: two channels (caller left, Agent right) at 16 kHz and 16 bits, decrypted by the api. Only a recording with status available has audio; any other status answers 409 recording_not_available. From 1.32.0 a read that finds the stored object missing marks the recording expired and answers the same. Every request is an audited content read.
Request
Set VOCAL_API to the base URL of your API and VOCAL_API_KEY to an API key with the recordings:read scope (Authentication and keys). Replace each placeholder, such as agt_... or <name>, with your own value.
curl "$VOCAL_API/v1/recordings/rec_.../audio" \
-H "Authorization: Bearer $VOCAL_API_KEY" \
-o answer.wavimport { writeFile } from 'node:fs/promises';
const response = await fetch(`${process.env.VOCAL_API}/v1/recordings/rec_.../audio`, {
headers: {
Authorization: `Bearer ${process.env.VOCAL_API_KEY}`,
},
});
console.log(response.status);
await writeFile('answer.wav', Buffer.from(await response.arrayBuffer()));import os
import requests
response = requests.get(
f"{os.environ['VOCAL_API']}/v1/recordings/rec_.../audio",
headers={
"Authorization": f"Bearer {os.environ['VOCAL_API_KEY']}",
},
)
print(response.status_code)
with open("answer.wav", "wb") as output:
output.write(response.content)Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
recording_id | path | RecordingId | yes | The id of a Call recording: rec_ and the row's UUIDv7 in 26 Crockford base32 characters. Opaque and safe to log. |
range | header | string | no | One byte range of the audio, bytes=<start>-<end>. A satisfiable range is answered 206; a malformed or unsatisfiable range is ignored and the whole audio is answered 200. |
Responses
| Status | Content type | Shape | Error codes |
|---|---|---|---|
200 | audio/wav | string (binary): The audio as a WAV file, decrypted by the api; bytes, not JSON. | |
206 | audio/wav | string (binary): The audio as a WAV file, decrypted by the api; bytes, not JSON. | |
400 | application/json | ErrorEnvelope | invalid_request |
401 | application/json | ErrorEnvelope | unauthenticated |
403 | application/json | ErrorEnvelope | forbidden |
404 | application/json | ErrorEnvelope | not_found |
409 | application/json | ErrorEnvelope | recording_not_available |
429 | application/json | ErrorEnvelope | rate_limited |
500 | application/json | ErrorEnvelope | internal_error |