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

# Voicemail tool

> Give a Vapi assistant direct control over voicemail with the voicemail tool, deciding when it reaches voicemail to leave a message or end the call.

## Overview

The Voicemail tool gives your assistant direct control over what happens when it reaches a voicemail system. Unlike [automatic voicemail detection](/calls/voicemail-detection), which operates independently of your assistant, this tool lets your assistant decide when it's hit voicemail and then either leave a configured message or silently end the call — depending on how you've set it up.

**Key benefits:**

* **Maximum flexibility** — assistant decides when to invoke the tool, and you decide what happens when it does
* **Customizable** — use template variables to personalize voicemails per call
* **Cost-effective** — only triggers when needed
* **Simple integration** — works like other built-in tools

## How it works

When you add the Voicemail tool to your assistant:

1. Your assistant listens for voicemail indicators (greetings mentioning "unavailable", "leave a message", etc.)
2. Upon detecting voicemail, the assistant calls the tool
3. Depending on how you've configured the tool, it either delivers your configured message or skips speaking entirely
4. The call ends automatically

> **Note**
>
> This approach differs from [automatic voicemail detection](/calls/voicemail-detection), which detects voicemail at the system
> level. The Voicemail tool puts detection and response entirely in the
> assistant's hands, so reliability depends heavily on your system prompt — see
> [Detection prompting](#detection-prompting) below for the indicators your prompt
> should explicitly call out.

## Voicemail behavior modes

When you configure the Voicemail tool, you choose what the caller hears once voicemail is detected:

| Mode                                | What happens                                                                                  | When to use it                                                                                                            |
| ----------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Use assistant voicemail message** | The tool falls back to the assistant's top-level `voicemailMessage` field, then the call ends | You want the message managed at the assistant level rather than on the tool                                               |
| **Use custom script**               | The tool speaks a message specific to this tool, then the call ends                           | You want a voicemail message tailored to this assistant or campaign, with optional dynamic content via template variables |
| **Skip speaking a voicemail**       | The call silently ends after the tool is invoked                                              | You explicitly don't want to leave a message but still need a reliable way to terminate calls on voicemail                |

### How the modes map to the underlying fields

Two fields work together to drive these modes: the tool's `messages` array (which can hold a `request-start` message with optional template variables) and the assistant-level `voicemailMessage` property. The dashboard radio buttons orchestrate these for you, but if you're configuring via the API, set the fields directly:

| Mode                            | Tool's `messages`            | Assistant's `voicemailMessage`  |
| ------------------------------- | ---------------------------- | ------------------------------- |
| Use assistant voicemail message | empty                        | set to the desired message      |
| Use custom script               | `request-start` with content | ignored — tool takes precedence |
| Skip speaking a voicemail       | empty                        | empty                           |

## Best practices

### Detection prompting

Be specific about voicemail indicators in your system prompt:

* "unavailable"
* "leave a message"
* "voicemail"
* "at the tone"
* "beep"

For auto-attendants and IVR menus, add cues like:

* "press 1 for..."
* "for a list of departments"
* "if you know your party's extension"

### Message structure

Keep voicemail messages:

* **Brief** — under 30 seconds
* **Clear** — state name, company, and purpose
* **Actionable** — include callback number or next steps
* **Professional** — match your brand voice

### Error handling

Consider edge cases:

* Long voicemail greetings
* Voicemail box full scenarios
* Systems requiring keypad input
* Auto-attendants that loop their menu

## Voicemail tool vs. automatic detection

| Feature               | Voicemail tool                                    | [Automatic detection](/calls/voicemail-detection) |
| --------------------- | ------------------------------------------------- | ------------------------------------------------- |
| Control               | Assistant-driven                                  | System-driven                                     |
| Flexibility           | High — custom logic and behavior modes            | Medium — predefined behavior                      |
| Cost                  | Lower — only when used                            | Higher — continuous monitoring                    |
| Setup complexity      | Simple — just add tool                            | Moderate — configure detection                    |
| Message customization | Custom message, assistant fallback, or no message | Limited to configured message                     |
| Detection accuracy    | Depends on prompt                                 | Provider-specific (Vapi, Google, etc.)            |

> **Warning**
>
> Avoid combining the **Voicemail tool** with **automatic detection**, as this
> could result in false positives and other complications.

> **Info**
>
> Choose the **Voicemail tool** when you need maximum flexibility and cost
> efficiency. Choose **automatic detection** when you need guaranteed
> system-level detection without relying on assistant prompting.

## Common use cases

* **Sales outreach** — personalized follow-up messages
* **Appointment reminders** — leave detailed appointment information
* **Customer service** — callback scheduling with ticket numbers
* **Lead qualification** — leave targeted messages based on lead data
* **Outbound prospecting (no message)** — cleanly terminate calls that hit voicemail when your strategy depends on live conversation

## Next steps

* [Configure the Voicemail tool](/tools/voicemail-tool/configure): create the tool, attach it to an assistant, and set its message
* Learn about other [built-in tools](/tools/default-tools)
* See how to create [Function tools](/tools/custom-tools) for your specific needs

> Learn how to use the assistant-controlled Voicemail tool for flexible voicemail handling

## Docs

- [Configure the Voicemail tool](https://docs.vapi.ai/tools/voicemail-tool/configure.md): Create a Vapi voicemail tool in the Dashboard or API, attach it to an assistant, prompt for voicemail detection, and set the message for each behavior mode.