Start recording

Rate limit: Per command · Burst: 4 · Refill: 1 req/s

Start a Recording of the call.

The 202 Accepted response confirms that the command was admitted. It does not confirm that recording has started or that recorded audio is available. Retain the returned recording_uuid to address this recording, and use the returned operation_uuid to correlate the recording lifecycle webhooks below.

Send POST /v1/sessions/{uuid}/recordings as soon as you receive the Session’s session_uuid. Choose the capture boundary with start_only_after_answer:

• By default, inbound and outbound phone Sessions start recording as soon as the current media path permits, including available early media.
• Set start_only_after_answer to true to durably wait for the canonical answer instead. If a waiting Session ends first, recording.failed is emitted.

Choose independently for each recording whether to include redacted periods and periods without recordable audio. Omit include_gaps or set it to false to remove those gaps from the artifact. Set it to true to include the gaps as silence.

Each Session independently allows up to four concurrent recordings, including duplicate both + mono recordings. Recordings waiting to start or finish count; recordings for another Session or a Room do not. A Room separately allows one active Room Recording at a time. A fifth request returns HTTP 409 with code concurrent_recording_limit_reached and reserves nothing. Stop one recording and wait for its terminal event before retrying with a new idempotency key. If the response remains 409 briefly, retry after release completes. Voice activity events and their detector configuration are optional and independent for every recording.

Output is 8 kHz mono mixed WAV (both legs combined). Format is not configurable.

Triggered webhooks:

• recording.became_available carries signed media_url and live_url capabilities; recording.failed is emitted instead if the recording does not become available.
• When enable_voice_activity_events is true, recording.speech.started and recording.speech.ended report customer speech transitions for the lifetime of this recording. Sensitivity and speech/silence confirmation durations are configurable.

Use media_url to start at byte zero and follow the growing Recording until EOF. After finalization, the same URL serves a finite, range-capable WAV. Use live_url to join near the current position. Anyone with either URL can access its capability until it expires. By default, it expires 24 hours after the lifecycle event is emitted.

Tip: Minimize confirmation playback delay. If you plan to play a recording back to the caller for confirmation, start streaming the media_url from the beginning into an S3 multipart upload as soon as recording.became_available provides it. After recording.ended, let the source stream reach EOF, then complete the multipart upload. Because most of the audio is already in S3, you can start playback without first transferring the entire recording after it ends.

Use media_url for this workflow. The live_url starts at the live edge and does not include audio recorded before you connect.

See Recording lifecycle events for complete payload schemas and examples.