# Voicemail detection

> Use `voicemail_detection` to hang up on, or leave a `message` for, outbound calls that reach a machine; closes as `voicemail`.

With `config.voicemail_detection` on, an agent that places a call and reaches an answering
machine leaves your message (if you set one) and hangs up. The call ends with
`close_reason: voicemail`, and a [batch](https://docs.talqing.com/telephony/batch-calling.md) dials that person again
later. Off by default; `voice` agents only (enabling it on `video` or `text` is refused).

```json
{
  "voicemail_detection": {
    "enabled": true,
    "message": "Hi {{userdata.name}}, this is Maya from Brightside Dental about your appointment tomorrow. Please call us back."
  }
}
```

| Field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `enabled` | boolean | `false` | Watch for voicemail on calls this agent places |
| `message` | string \| null | `null` | 1–2000 characters, spoken word for word, then hang up. `null` hangs up silently. Same substitutions as the greeting; `{{recording.notice}}` is refused here |

## How it decides

On a call it placed, the agent's model is given a `voicemail_detected` tool and calls it
when it hears a recorded greeting rather than a person. A person who picks up hears the
greeting with no detection delay, and detection costs nothing beyond the normal turn. The
model is told to wait for the machine's greeting to finish, but a greeting with a long
pause can make it act early and the start of the message may not be recorded.

Offered only on **outbound phone calls** and on [media streams](https://docs.talqing.com/channels/media-streams.md)
whose platform reports the call as outbound. Inbound, web and chat sessions never get the
tool.

On a [realtime model](https://docs.talqing.com/agents/realtime.md) the message is spoken by the model and may be
slightly reworded.

## What you see afterwards

| | |
| --- | --- |
| `close_reason` | `voicemail` |
| `status` | `completed` — **billed like any other call** (short: the machine's greeting plus your message) |
| Transcript | The machine's greeting as a caller turn, the `voicemail_detected` call, your message |
| Batch | Not reached: retried after `retry_after_minutes` while `max_attempts` allows, counted in `counts.voicemail`. Each retry that reaches the machine leaves the message again — set `max_attempts: 1` if once is enough |

Keep the message short and complete: who is calling, why, and what to do next.

## Next

- [Batch calling](https://docs.talqing.com/telephony/batch-calling.md): Retries and recipient statuses.
- [Close reasons](https://docs.talqing.com/observability/close-reasons.md): Every way a call can end.