> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anyreach.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Voicemail detection

> Detect answering machines on outbound calls and optionally leave a message.

Voicemail detection lets an agent recognize when an outbound call reaches an answering machine instead of a person, and decide whether to hang up or leave a message. It combines two signals: a beep model that listens for the answering-machine beep, and an LLM tool the model invokes when it hears a voicemail greeting.

Voicemail detection runs on **outbound telephone calls only**. The voicemail tool is added to the agent when the channel is `TELEPHONE`, the direction is `OUTBOUND`, and `voicemail_detection` is set on the agent config. It is never added for inbound calls or for web chat.

## How it works

Two independent detectors race to fire a single voicemail action:

```text theme={null}
Outbound call connects
        │
        ├── Beep model (beep-bot)         listens to call audio on a rolling
        │   anyreach-ai/beep-detector-v2  buffer, scoring recent audio for a beep
        │
        └── LLM voicemail tool            the model calls voicemail_detected
            (voicemail_detected)          when it hears a voicemail greeting
        │
        ▼
First detector to fire → voicemail action
        │
        ├── play_message set?  → speak the message, then hang up
        └── no play_message    → hang up immediately
```

The beep model is an ONNX model (`anyreach-ai/beep-detector-v2`, file `beep_detector.onnx`) that analyzes the call audio as a mel-spectrogram over a rolling buffer of recent audio. When the model's confidence for a beep exceeds `beep_detection_threshold`, the voicemail action fires. The LLM tool path fires independently when the model decides the greeting it hears matches the tool's description.

Whichever path fires first wins. The action only runs once per call.

## Configuration

Set `voicemail_detection` on the agent config with a `VoicemailDetectionConfig`.

| Field                      | Type    | Default  | Description                                                                                                |
| -------------------------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------- |
| `beep_detection_threshold` | number  | required | Confidence threshold (`0.0`–`1.0`) for the background beep model. Values above `0.95` give better results. |
| `beep_detection_timeout`   | integer | required | Maximum seconds to run background beep detection. Must be greater than `0`.                                |
| `tool_call_overrides`      | object  | `null`   | Overrides for the LLM voicemail tool. See below.                                                           |
| `play_message`             | object  | `null`   | Message to leave when voicemail is detected. Omit to hang up instead.                                      |

<Note>
  Setting `voicemail_detection` only takes effect on outbound telephone calls. On other channels and directions the config is ignored.
</Note>

### Tool call overrides

`tool_call_overrides` customizes the LLM tool the model calls when it hears a voicemail greeting. When omitted, the defaults below apply.

| Field                      | Type    | Default                                            | Description                                                                |
| -------------------------- | ------- | -------------------------------------------------- | -------------------------------------------------------------------------- |
| `name`                     | string  | `voicemail_detected`                               | Function name the LLM invokes.                                             |
| `description`              | string  | `whenever you hear 'you have reached a voicemail'` | When the model should call the tool.                                       |
| `beep_detection_threshold` | number  | `0.9`                                              | Confidence threshold for the beep that follows the voicemail voice prompt. |
| `beep_detection_timeout`   | integer | `10`                                               | Maximum seconds to wait for the beep after the voicemail voice prompt.     |

The voicemail tool itself takes no arguments. The model calls it purely as a signal that it has heard a voicemail greeting.

### Play message

`play_message` controls what the agent says before hanging up. Hanging up is implicit: with no `play_message`, the call ends as soon as voicemail is detected.

| Field      | Type    | Default  | Description                                                                   |
| ---------- | ------- | -------- | ----------------------------------------------------------------------------- |
| `message`  | string  | required | The message text or instructions. Supports template variables.                |
| `generate` | boolean | `false`  | Whether to generate the message with the LLM instead of speaking it verbatim. |

When `generate` is `false`, the agent speaks `message` verbatim. When `generate` is `true`, `message` is treated as instructions and the LLM generates the spoken reply from them. In both cases the agent hangs up once the message finishes playing.

## Leave a message vs hang up

<table>
  <thead>
    <tr><th>Goal</th><th>Configuration</th></tr>
  </thead>

  <tbody>
    <tr><td>Hang up silently on voicemail</td><td>Omit <code>play\_message</code></td></tr>
    <tr><td>Leave a fixed scripted message</td><td>Set <code>play\_message.message</code>, leave <code>generate</code> as <code>false</code></td></tr>
    <tr><td>Leave a contextual, LLM-generated message</td><td>Set <code>play\_message.message</code> to instructions, set <code>generate</code> to <code>true</code></td></tr>
  </tbody>
</table>

## Example

```json theme={null}
{
  "voicemail_detection": {
    "beep_detection_threshold": 0.97,
    "beep_detection_timeout": 15,
    "play_message": {
      "message": "Hi, this is Anyreach calling about your recent inquiry. Please call us back at your convenience. Thank you.",
      "generate": false
    }
  }
}
```

This agent listens for a beep with a confidence threshold of `0.97`, runs the background beep model for up to `15` seconds, and leaves a fixed message before hanging up when voicemail is detected.

## Tuning

<AccordionGroup>
  <Accordion title="Reducing false positives">
    Raise `beep_detection_threshold` toward `1.0`. The config description recommends keeping it above `0.95`. A higher threshold makes the beep model more conservative, so it is less likely to mistake other sounds for a voicemail beep.
  </Accordion>

  <Accordion title="Catching slow voicemail systems">
    Increase `beep_detection_timeout` so the beep model keeps listening long enough for systems with a longer greeting before the beep.
  </Accordion>

  <Accordion title="Tuning when the LLM flags voicemail">
    Adjust `tool_call_overrides.description` to match the greeting phrasing you expect, so the model calls the voicemail tool at the right moment.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Abilities and actions" icon="bolt" href="/agents/abilities-and-actions">
    How actions like play-message and hang-up are grouped into tools the model calls.
  </Card>

  <Card title="Outbound and caller ID" icon="phone-arrow-up-right" href="/telephony/outbound-and-caller-id">
    Place outbound calls and set the caller ID voicemail detection runs on.
  </Card>

  <Card title="Campaigns overview" icon="bullhorn" href="/campaigns/overview">
    Run outbound calls at scale, where voicemail detection matters most.
  </Card>
</CardGroup>