> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildwithchirp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Voicemails

> Receive, manage, and transcribe voicemails left by callers

Voicemails are created when a call is routed to voicemail, either by sending the `send_to_voicemail` [call command](/calling/call-commands#send-to-voicemail) or automatically based on your app's default calling behavior.

Voicemails can have a configurable maximum duration and an optional custom greeting URL, set through your app's calling configuration.

## How Voicemails Work

1. A call is sent to voicemail via the `send_to_voicemail` command or your app's default behavior.
2. The caller hears a greeting (custom or default) and leaves a message.
3. Chirp records the message and creates a voicemail record.
4. A `calls.voicemail.received` webhook fires when the voicemail is ready.
5. If transcription is enabled, the voicemail includes a text transcription.

## List Voicemails

Retrieve all voicemails for your app, with pagination.

```bash icon="terminal" title="List voicemails" theme={null}
curl -X GET "https://api.buildwithchirp.com/v1/calls/voicemails?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_APP_KEY"
```

```json icon="json" title="Response" theme={null}
{
  "data": [
    {
      "id": "call_vm_abc123",
      "callId": "call_xyz789",
      "callerNumber": "+15551234567",
      "callerChannel": "pstn",
      "duration": 30,
      "isRead": false,
      "transcription": "Hi, I was calling about my order. Please call me back.",
      "recordingId": "call_rec_abc123",
      "createdAt": "2026-01-15T10:35:00Z"
    }
  ],
  "totalCount": 1
}
```

| Query Parameter | Type    | Default | Description                        |
| --------------- | ------- | ------- | ---------------------------------- |
| `limit`         | integer | 20      | Number of results per page (1-100) |
| `offset`        | integer | 0       | Offset for pagination              |

## Get Voicemail Details

Retrieve a specific voicemail by ID. The response includes the transcription if available.

```bash icon="terminal" title="Get a voicemail" theme={null}
curl -X GET https://api.buildwithchirp.com/v1/calls/voicemails/call_vm_abc123 \
  -H "Authorization: Bearer YOUR_APP_KEY"
```

```json icon="json" title="Response" theme={null}
{
  "id": "call_vm_abc123",
  "callId": "call_xyz789",
  "callerNumber": "+15551234567",
  "callerChannel": "pstn",
  "duration": 30,
  "isRead": false,
  "transcription": "Hi, I was calling about my order. Please call me back.",
  "recordingId": "call_rec_abc123",
  "createdAt": "2026-01-15T10:35:00Z"
}
```

<Tip>
  If the voicemail has an associated `recordingId`, you can use the [Recordings API](/calling/recordings#get-recording-details) to download the audio file.
</Tip>

## Mark as Read

Update a voicemail to mark it as read.

```bash icon="terminal" title="Mark voicemail as read" theme={null}
curl -X PATCH https://api.buildwithchirp.com/v1/calls/voicemails/call_vm_abc123 \
  -H "Authorization: Bearer YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "isRead": true }'
```

```json icon="json" title="Response" theme={null}
{
  "id": "call_vm_abc123",
  "callId": "call_xyz789",
  "callerNumber": "+15551234567",
  "callerChannel": "pstn",
  "duration": 30,
  "isRead": true,
  "transcription": "Hi, I was calling about my order. Please call me back.",
  "recordingId": "call_rec_abc123",
  "createdAt": "2026-01-15T10:35:00Z"
}
```

## Delete a Voicemail

Permanently delete a voicemail.

```bash icon="terminal" title="Delete a voicemail" theme={null}
curl -X DELETE https://api.buildwithchirp.com/v1/calls/voicemails/call_vm_abc123 \
  -H "Authorization: Bearer YOUR_APP_KEY"
```

```json icon="json" title="Response" theme={null}
{
  "message": "Voicemail deleted"
}
```

## Webhook

When a caller leaves a voicemail, Chirp sends a `calls.voicemail.received` webhook to your configured webhook URL. Use this to notify your team, trigger auto-replies, or start processing the voicemail transcription.