> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.rydhm.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.rydhm.ai/_mcp/server.

# AI voicemail

Leaving voicemails is where reps lose the most time: waiting through the greeting, the beep, the same message for the fortieth time. With AI voicemail the rep presses one button and moves straight to the next call. The AI stays on the line, waits for the beep, says the message in a natural voice, and hangs up.

> **Warning**
>
> **AI voicemail is off until a workspace admin turns it on**, in **Sales calls** → **Settings** → **Let the AI leave voicemails** (from a signed-in session, `PATCH /v1/workspace/policies { "aiVoicemail": true }`; API keys can't change it). While it's off, `leaveVoicemail` answers `403` with `error: "ai_voicemail_off"`. AI voices are "artificial voices" under the TCPA (FCC declaratory ruling, Feb 2024). Get the person's prior express written consent before an AI voice speaks to them, and pass `consent` so the call's record shows where it came from (see [Record the consent](#record-the-consent)). Some states add their own rules. Check with your own counsel before you use it. This is not legal advice.

## Leave one

From your server, with `calls:write`, while the call is live:

#### TypeScript

```typescript
// A message written by the AI from the call's context:
await rydhm.repCalls.leaveVoicemail(callId);

// Or your own words, in a chosen voice, keeping the rep on the call to listen:
await rydhm.repCalls.leaveVoicemail(callId, {
  message: "Hi Dana, it's Maya from Rydhm. I'll send the pricing we talked about. Call me back on this number.",
  voice: "aura-2-thalia-en",
  releaseRep: false,
});
```

#### Python

```python
client.rep_calls.leave_voicemail(call_id)

client.rep_calls.leave_voicemail(
    call_id,
    message="Hi Dana, it's Maya from Rydhm. I'll send the pricing we talked about.",
    voice="aura-2-thalia-en",
    release_rep=False,
)
```

#### HTTP

```bash
curl -X POST https://api.rydhm.ai/v1/rep-calls/$CALL_ID/voicemail \
  -H "Authorization: Bearer $RYDHM_API_KEY" -H "Content-Type: application/json" \
  -d '{}'
```

| Field        | Default                                           | What it does                                                                                                                                                                                                                       |
| ------------ | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `message`    | Written by the AI                                 | What to say, up to 500 characters: your app's own script for this prospect. Without it, the AI writes a short message from the call's `context`: the prospect's name, the goal of the call, your notes and `playbook`.             |
| `voice`      | The rep's voice, else the workspace's, else Blake | An `id` from [`GET /v1/voices`](#choose-the-voice), for this voicemail only. Any Cartesia voice id or Deepgram Aura or Flux voice (`aura-2-thalia-en`) works too; anything else answers `400 invalid_voice`.                       |
| `releaseRep` | `true`                                            | Take the rep off the call at once, so they can dial the next one. `false` keeps them on the call to **listen** while the AI speaks: their microphone is taken off the call, so nothing they say lands in the prospect's voicemail. |
| `consent`    | None                                              | `{ source, obtainedAt? }`: where the prospect's consent to an AI voice came from. Kept on the call and in the audit log. See [Record the consent](#record-the-consent).                                                            |

The call's status becomes `leaving_voicemail` straight away. It answers `409 not_answered` while the call still rings (ask once a voicemail picks up), `409 call_over` when the call has already ended, `409 not_outbound` on a callback (someone calling in), and `409 ai_not_in_call` in the first moments of a call, before Rydhm's listener has joined: try again a second later. Pair it with detection: when `call.answered` says `by: "machine"`, offer the rep the button, or leave the voicemail automatically:

```typescript
for await (const e of rydhm.repCalls.events(call.id)) {
  if (e.type === "call.answered" && e.data.by === "machine") await rydhm.repCalls.leaveVoicemail(call.id);
}
```

## Choose the voice

Your reps talk in their own voices. Rydhm's voice speaks only its own lines: the AI voicemail, and the recording notice where everyone on a call must be told. A call uses one voice, chosen in this order:

1. The `voice` you send with the voicemail (that voicemail only).
2. The rep's own voice: `voicemailVoice` on `PUT /v1/reps/{externalId}`.
3. The workspace's voice: an admin sets it in **Sales calls** → **Settings** → **Voicemail voice**.
4. Rydhm's default, Blake.

Leave a rep's `voicemailVoice` as `null` and they follow the workspace's voice. In the Rydhm app that reads "Same as the team".

To let people pick a voice in your app, list them with `GET /v1/voices` (`calls:read`). Each voice has a name, a short description and `sampleUrl`: an MP3 of it reading a voicemail. It's a static file, so playing it costs nothing and needs no key. `default` is the voice used when nothing else names one: the workspace's (`source: "workspace"`) or Rydhm's (`source: "rydhm"`).

#### TypeScript

```typescript
const voices = await rydhm.voices.list();
// Show voices.items (name, description, ▶ sampleUrl), then save the one picked:
await rydhm.reps.upsert("usr_4821", { name: "Maya Patel", voicemailVoice: voices.items[3].id });
// null follows the workspace's voice again:
await rydhm.reps.upsert("usr_4821", { name: "Maya Patel", voicemailVoice: null });
```

#### Python

```python
voices = client.voices.list()
print(voices.default.name)  # "Blake"
for v in voices.items:
    print(v.name, v.description, v.sample_url)

client.reps.upsert("usr_4821", name="Maya Patel", voicemail_voice=voices.items[3].id)
```

#### HTTP

```bash
curl https://api.rydhm.ai/v1/voices -H "Authorization: Bearer $RYDHM_API_KEY"
```

```json
{
  "default": { "id": "a167e0f3-df7e-4d52-a9c3-f949145efdab", "name": "Blake", "source": "rydhm" },
  "items": [
    {
      "id": "a167e0f3-df7e-4d52-a9c3-f949145efdab",
      "name": "Blake",
      "description": "Energetic · Male · US",
      "language": "en",
      "sampleUrl": "https://app.rydhm.ai/voicemail-voices/a167e0f3-df7e-4d52-a9c3-f949145efdab.mp3"
    }
  ]
}
```

A voice that isn't on the list (any Cartesia or Deepgram voice Rydhm can speak) still works; it has no sample, and `default.name` reads "Custom voice".

## Record the consent

AI voices are "artificial voices" under the TCPA (FCC declaratory ruling, Feb 2024). Get the person's prior express written consent before an AI voice speaks to them, and pass `consent` so the call's record shows where it came from.

| Field                | Required | What it is                                                                                                 |
| -------------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| `consent.source`     | Yes      | Where the consent came from, in your words: a form, a signed agreement, a CRM record. 1 to 255 characters. |
| `consent.obtainedAt` | No       | When the person gave it (ISO 8601). It can't be in the future.                                             |

#### TypeScript

```typescript
await rydhm.repCalls.leaveVoicemail(callId, {
  consent: { source: "Demo request form, acme.com/demo", obtainedAt: "2026-11-10T09:30:00Z" },
});
```

#### Python

```python
client.rep_calls.leave_voicemail(
    call_id,
    consent={"source": "Demo request form, acme.com/demo", "obtained_at": "2026-11-10T09:30:00Z"},
)
```

#### HTTP

```bash
curl -X POST https://api.rydhm.ai/v1/rep-calls/$CALL_ID/voicemail \
  -H "Authorization: Bearer $RYDHM_API_KEY" -H "Content-Type: application/json" \
  -d '{"consent":{"source":"Demo request form, acme.com/demo","obtainedAt":"2026-11-10T09:30:00Z"}}'
```

* It's kept on the call, with the time Rydhm recorded it: `GET /v1/rep-calls/{id}` returns it as `voicemail.consent` (`{ source, obtainedAt, recordedAt }`), next to `voicemail.requestedAt`, the time the AI was asked to leave the message.
* It's in the workspace's [audit log](/workspace/security#audit-log), with the voicemail request.
* A `consent` without a `source`, with a `source` over 255 characters, or with an `obtainedAt` that isn't a date or is in the future answers `400 invalid_consent`.
* `consent` is optional. Rydhm doesn't check it: it keeps what your app sends. Getting the consent is up to you.

## Who the message says is calling

The message names the rep (their `name` in `PUT /v1/reps/{externalId}`) and the company they call for: the call's `context.seller.company`, or your Rydhm workspace's name when the context has none. With **The AI says it's an AI** on, a message the AI writes opens with "Hi Dana, this is an automated message on behalf of Maya at Acme", and a `message` of yours gets that line in front unless it already says it's automated. The call-back number is the number the call went out from.

## What happens on the call

1. The AI takes over the line, and the rep is released (unless `releaseRep: false`).
2. It waits for the voicemail greeting to end and the beep (`call.beep`).
3. It speaks the message, then hangs up.
4. You get `call.voicemail_left` with the exact words and the voice, then `call.ended` with `outcome: "voicemail_left"`. The words are also kept on the call as `voicemail.text` (with `voicemail.by: "ai"`; `voicemailText` and `voicemailBy` still work), and the `call.voicemail_left` [webhook](/developers/webhooks#rep-calls-and-the-onboarding-coach) goes out. Webhooks carry the voice and the length, never the words.

**When it doesn't happen.** If the AI can't leave the message (the call wasn't answered yet, it's a callback, the line was gone, or the message couldn't be spoken), you get `call.voicemail_failed` with a `reason` (`not_answered`, `not_outbound`, `line_gone`, `no_audio`), and the call goes on or ends as it would have. Show it to the rep: they can leave their own.

**The rep's own message.** When a machine answered and the rep speaks their own message after the beep (eight words or more), that is a voicemail left too: `call.voicemail_left` with `by: "rep"` and the rep's words as transcribed, `voicemailBy: "rep"` on the call, and the call ends as `voicemail_left`. It isn't billed as an AI voicemail.

On a callback that nobody answered, the last step of the pool's routing can be voicemail: then the **caller** leaves a message. It arrives the same way, with `by: "caller"` and their number in `from` on the event, and `voicemailBy: "caller"` on the call.

In the transcript, the AI's lines have `speaker: "ai"`.

## Disclosure and recording

* Transcribing a call records it in the legal sense, and some states require everyone on the call to be told; on a live call, your rep says it. The workspace's disclosure setting (**Sales calls** → **Settings** → **Recording, and telling people** → **The AI says it's an AI**, on by default; `repCallDisclosure` in the workspace policies) makes an AI voicemail say it's an automated message on the rep's behalf, and tells a caller leaving a message that it's recorded and transcribed.
* When the call is [recorded](/engine/rep-calls#recordings), the AI voicemail is in the recording, on the rep's side (the left channel).
* [Calling hours](/engine/rep-calls#calling-hours), your **Do not call** list and the US-only dialling rules apply to rep calls exactly as to AI calls. See [US-only dialling](/channels/phone#us-only-dialling).

## What it costs

Provisional while rep calls are in preview: \$0.02 for each AI voicemail, on top of the call's minutes. Final prices will be on the [Billing](/workspace/billing) page before launch.