Recordings and transcriptions
Recordings come from calls (record on create, the record_start action, CoXML <Record> and <Dial record>),
conferences, voicemail and AI agents. Transcriptions come from <Record transcribe> and record_start with
transcription. Paths are relative to https://api.contactivity.io/v1/projects/{project_id}; see the
overview for auth, errors and paging.
| Method | Path | Scope | Purpose |
|---|---|---|---|
| GET | /recordings |
recordings:read |
List recordings (paged) |
| GET | /recordings/{recording_id} |
recordings:read |
Fetch a recording |
| GET | /recordings/{recording_id}/media |
recordings:read |
Download the audio (302 to a signed link) |
| DELETE | /recordings/{recording_id} |
recordings:write |
Archive a recording (audio kept) |
| GET | /transcriptions |
recordings:read |
List transcriptions (paged) |
| GET | /transcriptions/{transcription_id} |
recordings:read |
Fetch a transcription |
| DELETE | /transcriptions/{transcription_id} |
recordings:write |
Archive a transcription |
The recording object
| Field | Type | Description |
|---|---|---|
id |
string | RE… |
call_id, conference_id |
string or null | |
from, to |
string or null | The call's numbers (E.164); null without a call (conference recordings) |
status |
string | in_progress, paused, stopped, processing, completed, absent, failed |
source |
string | call, conference, coxml_record, voicemail, api, ai_agent |
channels |
integer | 1 or 2 |
format |
string | wav or mp3 |
duration_secs |
integer or null | |
price |
null | Recordings are not charged per recording today |
created_at |
timestamp | |
media_url |
string | This recording's /media URL (needs the API key) |
GET /recordings filters: call_id, conference_id, from, to (the call's numbers, exact; +1NXXNXXXXXX also
matches a stored 1NXXNXXXXXX), source, created_after (inclusive), created_before
(exclusive), as RFC 3339 or YYYY-MM-DD; plus limit, starting_after. Errors: 400 invalid_parameter.
GET /recordings/{id}/media?format=wav|mp3 (default: the stored format) answers 302 with Location set to a
signed link valid for 10 minutes. Errors: 400 invalid_parameter (param format), 404 not_found,
404 media_not_available (no audio yet, or not in that format), 503 storage_unavailable.
curl -sL -o call.mp3 "https://api.contactivity.io/v1/projects/$PROJECT_ID/recordings/$RECORDING_ID/media?format=mp3" \
-H "Authorization: Bearer $CONTACTIVITY_API_KEY"DELETE /recordings/{id} archives the recording: 204; 404 not_found; 409 archived (already archived). The
audio is kept; the recording leaves lists (?archived=true lists it) and GET by id still returns it with
archived_at set.
The transcription object
| Field | Type | Description |
|---|---|---|
id |
string | TR… |
recording_id |
string | |
call_id |
string or null | |
status |
string | in_progress, completed, failed |
language |
string | |
text |
string or null | |
confidence |
null | Not stored today |
duration_secs |
integer or null | |
price |
money or null | Set once completed |
error |
string or null | Why it failed |
created_at |
timestamp |
GET /transcriptions filters: recording_id, call_id, created_after, created_before; plus limit,
starting_after.
curl "https://api.contactivity.io/v1/projects/$PROJECT_ID/transcriptions?recording_id=$RECORDING_ID" \
-H "Authorization: Bearer $CONTACTIVITY_API_KEY"GET and DELETE /transcriptions/{id}: 404 not_found when absent; delete archives it and returns 204
(409 archived when already archived).
Recording and transcription events (call.recording.completed, call.transcription.completed,
call.transcription.failed) are listed in events.md.