Prerequisites
- A project-bound platform API key (
abl_…) with therecordings.readscope. Send it in thex-api-keyheader or asAuthorization: Bearer abl_…. The API refuses Studio user JWTs, JWT App assertions, and publicpk_keys with403 PLATFORM_API_KEY_REQUIRED. - Call recording enabled for the tenant.
- The project ID and the session ID.
Workflow and use cases
- Get all recordings for the session.
- Check
data.status. Ifdata.retryableistrue, retry with backoff. Stop retrying when it isfalse. - For each file that has a URL, check
urlKind. Forsignedandexternal, send aGETrequest to the URL. Forproxied, prefix the relative URL with the API host and send aGETrequest. - Stream the media. A
proxiedURL calls the stream endpoint, which supports byte ranges.
Authorization header when you request a media URL.
List of endpoints
Behavior to know
- A session can produce several recordings, such as after a transfer. Each recording can have several files, such as separate caller and agent channels.
- An HTTP
200response does not mean the media is available. Thedata.statusfield issuccess,partial,call_in_progress,media_in_progress, ormedia_unavailable. - Media URLs are short-lived. The default lifetime is 900 seconds and the maximum is 3600 seconds. The
expiresInfield isnullfor external URLs. Treat every media URL as a bearer secret. - Use the
dispositionparameter to chooseattachment(default) to download the file orinlineto play it in a browser. - A session allows up to 64 recordings and, by default, up to 32 stored files across them. Exceeding a limit returns
413. - When the API issues at least one media URL, it records an audit event attributed to the calling key.