Call Recordings

You can record any active call by sending a start_recording command. Once the recording finishes, the audio file is stored and made available through the recordings API.

Starting a Recording

To begin recording, send a start_recording call command:

Start recording a call

curl -X POST https://api.buildwithchirp.com/v1/calls/call_abc123/commands \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "start_recording",
    "format": "mp4"
  }'

Supported Formats

Format	Description
`mp4`	MPEG-4 audio (default)
`ogg`	Ogg Vorbis audio
`webm`	WebM audio

Stopping a Recording

You can stop a recording explicitly with the stop_recording command, or the recording ends automatically when the call ends.

Stop recording

curl -X POST https://api.buildwithchirp.com/v1/calls/call_abc123/commands \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "stop_recording" }'

Recording Lifecycle

Recordings move through these statuses:

Status	Description
`recording`	Actively capturing audio
`processing`	Audio is being processed and uploaded to storage
`completed`	Recording is ready to download
`failed`	Processing failed

When a recording reaches the completed status, a calls.recording.completed webhook is fired.

List Recordings

Retrieve all recordings for a specific call.

List recordings for a call

curl -X GET https://api.buildwithchirp.com/v1/calls/call_abc123/recordings \
  -H "Authorization: Bearer YOUR_APP_KEY"

Response

{
  "data": [
    {
      "id": "call_rec_abc123",
      "callId": "call_abc123",
      "status": "completed",
      "format": "mp4",
      "duration": 120,
      "fileUrl": "https://storage.example.com/recordings/call_rec_abc123.mp4?signed=...",
      "fileSize": 1048576,
      "startedAt": "2026-01-15T10:30:00Z",
      "endedAt": "2026-01-15T10:32:00Z",
      "createdAt": "2026-01-15T10:30:00Z"
    }
  ],
  "totalCount": 1
}

Get Recording Details

Retrieve a specific recording by ID. For completed recordings, the response includes a signed download URL that is valid for one hour.

Get a recording

curl -X GET https://api.buildwithchirp.com/v1/calls/recordings/call_rec_abc123 \
  -H "Authorization: Bearer YOUR_APP_KEY"

Response

{
  "id": "call_rec_abc123",
  "callId": "call_abc123",
  "status": "completed",
  "format": "mp4",
  "duration": 120,
  "fileUrl": "https://storage.example.com/recordings/call_rec_abc123.mp4?signed=...",
  "fileSize": 1048576,
  "startedAt": "2026-01-15T10:30:00Z",
  "endedAt": "2026-01-15T10:32:00Z",
  "createdAt": "2026-01-15T10:30:00Z"
}

The fileUrl is a time-limited signed URL. If you need to download the file later, request the recording details again to get a fresh URL.

Download a Recording

To download the recording file, fetch the fileUrl from the get recording response:

Download recording file

curl -o recording.mp4 "https://storage.example.com/recordings/call_rec_abc123.mp4?signed=..."

The signed URL is valid for one hour from the time it was generated. After expiration, request the recording details again to get a new URL.

Delete a Recording

Delete a recording from both storage and the database.

Delete a recording

curl -X DELETE https://api.buildwithchirp.com/v1/calls/recordings/call_rec_abc123 \
  -H "Authorization: Bearer YOUR_APP_KEY"

Response

{
  "message": "Recording deleted"
}

Deleting a recording is permanent. The audio file is removed from storage and the record is soft-deleted from the database.

Webhook

When a recording finishes processing, Chirp sends a calls.recording.completed webhook to your configured webhook URL. Use this to trigger downstream workflows such as transcription or archival.

Getting Started

Concepts

Webhooks

SMS

WhatsApp

Calling

Resources

Call Recordings

Starting a Recording

Supported Formats

Stopping a Recording

Recording Lifecycle

List Recordings

Get Recording Details

Download a Recording

Delete a Recording

Webhook

​Starting a Recording

​Supported Formats

​Stopping a Recording

​Recording Lifecycle

​List Recordings

​Get Recording Details

​Download a Recording

​Delete a Recording

​Webhook

Starting a Recording

Supported Formats

Stopping a Recording

Recording Lifecycle

List Recordings

Get Recording Details

Download a Recording

Delete a Recording

Webhook