Voicemails

Voicemails are created when a call is routed to voicemail, either by sending the send_to_voicemail call command 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

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

List Voicemails

Retrieve all voicemails for your app, with pagination.

List voicemails

curl -X GET "https://api.buildwithchirp.com/v1/calls/voicemails?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_APP_KEY"

Response

{
  "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.

Get a voicemail

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

Response

{
  "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"
}

If the voicemail has an associated recordingId, you can use the Recordings API to download the audio file.

Mark as Read

Update a voicemail to mark it as read.

Mark voicemail as read

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 }'

Response

{
  "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.

Delete a voicemail

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

Response

{
  "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.

Getting Started

Concepts

Webhooks

SMS

WhatsApp

Calling

Resources

How Voicemails Work

List Voicemails

Get Voicemail Details

Mark as Read

Delete a Voicemail

Webhook

​How Voicemails Work

​List Voicemails

​Get Voicemail Details

​Mark as Read

​Delete a Voicemail

​Webhook

How Voicemails Work

List Voicemails

Get Voicemail Details

Mark as Read

Delete a Voicemail

Webhook