Skip to main content

Recordings

Tags: recordings, voice

Download recorded voice calls. Audio is only available when the workspace has Enable Audio Recording turned on and the call completed with stored audio. Recorded call audio may contain protected health information (PHI); treat it with the same care as any other patient data.

Resources​

Request and response models used by the endpoints on this page.

CallRecordingDownloadUrlResponse​

FieldTypeRequiredDescription
downloadUrlString✓Short-lived presigned URL that downloads the complete call recording as a WAV file.
expiresInInteger✓Number of seconds the URL remains valid, after the server-side maximum is applied.
mimeTypeString✓Content type of the downloaded file (always audio/wav).

Example:

{
  "downloadUrl": "string"  // String, Short-lived presigned URL that downloads the complete call recording as a WAV file.,
  "expiresIn": 0  // Integer, Number of seconds the URL remains valid, after the server-side maximum is applied.,
  "mimeType": "string"  // String, Content type of the downloaded file (always `audio/wav`).
}

Endpoints​

Download Recording​

GET /api/v2/w/{workspace_uuid}/recordings/chat/{chat_id}/audio.wav

Description:

Download a completed call recording as a single WAV file

Returns the full call for chat_id as one standard WAV file, assembled from the stored audio onto a single timeline (overlapping speech is mixed). The result is suitable for any HTML5 audio player or wavesurfer.js. You only need the chat ID — no chunk enumeration or storage keys are involved.

For API integrations, prefer GET /chat/{chat_id}/download-url so large recording downloads do not stream through the Gravity Rail API process.

Manager-owned and direct-message chats stay private to their participants: a caller who is not a participant receives 403 Forbidden for those chats even with the chats:read scope.

Returns 404 Not Found when no audio is stored for the chat (recording was off, the call was too short, or the chat is not a voice chat).

Authorization: Requires chats:read scope

Parameters:

  • chat_id (Integer)

Get Download URL​

GET /api/v2/w/{workspace_uuid}/recordings/chat/{chat_id}/download-url

Description:

Get a short-lived URL for a completed call recording

Return a short-lived presigned URL for downloading a completed call recording as one WAV file. This is the recommended integration endpoint for workflows such as "call ended → download the recording": your client downloads the bytes directly from object storage instead of streaming them through the Gravity Rail API.

When a ready Twilio-native recording exists for the chat, the URL points at the derived mono playback WAV (both parties mixed to one channel) — the same object GET /chat/{chat_id}/audio.wav serves — and no chunk assembly happens. Ingest writes that mono object as a deterministic sibling of the canonical dual-channel WAV, so a ready recording always has it. Otherwise the first request assembles the recording from stored audio chunks and caches the full-call WAV in workspace-scoped storage; later requests reuse that cached object and only mint a fresh presigned URL.

The expires_in query parameter (seconds) is optional; Gravity Rail caps it at the server-configured maximum and defaults to 3600 seconds.

Manager-owned and direct-message chats stay private to their participants: a caller who is not a participant receives 403 Forbidden for those chats even with the chats:read scope.

Returns 404 Not Found when no audio is stored for the chat (recording was off, the call was too short, or the chat is not a voice chat).

Authorization: Requires chats:read scope

Parameters:

  • chat_id (Integer)
  • expires_in (Integer) — min: 60

Response: See CallRecordingDownloadUrlResponse