Skip to main content
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

  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.
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 ParameterTypeDefaultDescription
limitinteger20Number of results per page (1-100)
offsetinteger0Offset 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.