> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/platform-api/conversations/voicemail.md).

# Voicemail

Ringless voicemail is delivered through a channel use case. Define a `ringless_voicemail` use case, assign phone numbers to it, and bind it to the service that owns the workflow (see [Use Cases & Bindings](/developer-guide/platform-api/workspaces/use-cases.md)). Voicemail sends are then queued through the channel management API.

{% hint style="info" %}
Ringless voicemail send and list routes belong to the Channel Manager API and are not published in the Platform API OpenAPI document. Their contract remains manual here because no public operation is available to embed.
{% endhint %}

## Send a Voicemail

`POST /v1/ringless-voicemail`

Queues one ringless voicemail drop to a recipient. Requires the `ringless-voicemail:send` scope on the target setup. The sender number is picked at random from the phone numbers assigned to the use case, and the audio is handed to the voicemail delivery provider.

### Request Body (multipart form)

| Field                    | Type          | Required | Description                                             |
| ------------------------ | ------------- | -------- | ------------------------------------------------------- |
| `use_case_id`            | string (UUID) | Yes      | ID of the `ringless_voicemail` use case to send through |
| `recipient_phone_number` | string        | Yes      | Destination phone number in E.164 format (US/CA)        |
| `audio`                  | file          | Yes      | MP3 audio, 10-60 seconds, up to 8 MB                    |

### Response (201)

| Field                 | Type   | Description                                             |
| --------------------- | ------ | ------------------------------------------------------- |
| `voicemail_id`        | string | Correlation key for tracking the drop's delivery status |
| `sender_phone_number` | string | E.164 phone number the voicemail is sent from           |

### Error Responses

| Status | Condition                                                                                               |
| ------ | ------------------------------------------------------------------------------------------------------- |
| 401    | Missing, expired, or invalid bearer token                                                               |
| 403    | Token lacks the required scope or access to this use case's setup                                       |
| 404    | Use case not found, not bound to `ringless_voicemail`, or has no assigned phone numbers                 |
| 413    | Audio file exceeds 8 MB                                                                                 |
| 422    | Audio is not a valid MP3, duration is outside 10-60 seconds, or the delivery provider rejected the send |

## List Voicemails

`GET /v1/ringless-voicemail`

Lists voicemail drops for a telephony setup. `setup_id` is required; `use_case_id` can narrow the results further.

### Query Parameters

| Parameter                | Type                | Description                                                          |
| ------------------------ | ------------------- | -------------------------------------------------------------------- |
| `use_case_id`            | string (UUID)       | Optional filter for voicemails sent under this use case              |
| `setup_id`               | string (UUID)       | Required setup whose voicemail records should be listed              |
| `status`                 | string (repeatable) | Filter to voicemails with any of these statuses                      |
| `recipient_phone_number` | string              | Filter to voicemails sent to this E.164 number                       |
| `sort_by`                | string (repeatable) | `+created_at` or `-created_at` (default `-created_at`, newest first) |
| `limit`                  | integer (1-200)     | Maximum items to return (default 50)                                 |
| `continuation_token`     | string              | Opaque page cursor from a prior response                             |

Each returned item includes `voicemail_id`, `setup_id`, `use_case_id`, `recipient_phone_number`, `status`, the provider's native ID once known, and `created_at`/`updated_at` timestamps.

## Delivery Status Lifecycle

| Status          | Description                                                                |
| --------------- | -------------------------------------------------------------------------- |
| `pending`       | Queued; no delivery report received yet                                    |
| `delivered`     | Successfully delivered (terminal)                                          |
| `skipped`       | Provider skipped the send, for example do-not-contact filtering (terminal) |
| `failed`        | Failure during the send attempt (terminal)                                 |
| `not_delivered` | Delivery provider reported non-delivery after the attempt (terminal)       |

Delivery callbacks update the voicemail record only. The current callback path does not publish status changes to the workspace SSE stream. `channel.voicemail_status` can still appear in compatibility event schemas, but clients should not wait for that event as a delivery receipt.

## Operational Model

Use application-level idempotency and eligibility checks before triggering a workflow that can produce outbound voicemail. Treat voicemail as an externally visible contact attempt subject to consent, opt-out, quiet-hour, and campaign-governance rules.

Use case creation and service binding are documented under Channel Manager. If the channel is not yet enabled for your workspace, submit an access request through the Channels endpoint:

{% content-ref url="/pages/34HJnXyVQXrBvV9THPG9" %}
[Channel Manager](/developer-guide/platform-api/conversations/channel-manager.md)
{% endcontent-ref %}

{% content-ref url="/pages/so4nsJwWi9MP6wHDNhYY" %}
[Channels](/developer-guide/platform-api/conversations/channels.md)
{% endcontent-ref %}

## Related Guide

* [Use Cases & Bindings](/developer-guide/platform-api/workspaces/use-cases.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/developer-guide/platform-api/conversations/voicemail.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.