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

# Voicemail Tool

## 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

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                           |

## Configuration

Add the voicemail tool to your assistant and configure your system prompt to invoke it when voicemail is detected.

1. Go to **Tools** in the left nav and click **Create Tool**.
2. Select **Voicemail** as the tool type.
3. Give the tool a name and description. The description tells the LLM when to invoke the tool — keep it consistent with the voicemail-detection instruction you'll add to your system prompt in step 7. Example: *"Leave a voicemail message when you detect you've reached a voicemail system or auto-attendant."*
4. Under **Voicemail Script**, choose a behavior mode: **Use assistant voicemail message**, **Use custom script**, or **Skip speaking a voicemail**. See [Voicemail behavior modes](#voicemail-behavior-modes) for details.
5. Save the tool.
6. Attach the tool to your assistant: open the assistant, go to **Tools**, and add the voicemail tool you just created.
7. Add a voicemail-detection instruction to your assistant's system prompt. Without this, the LLM won't know when to call the tool. See [Detection prompting](#detection-prompting) for indicators to include.

![Voicemail tool configuration](https://files.buildwithfern.com/https://vapi.docs.buildwithfern.com/d9ff881da0a8dd77bea3ef706822a38701cdcfd6a85b3880c5cf576e146096af/static/images/tools/voicemail-tool-config.png)

Add the voicemail tool to your assistant's `tools` array, and include a voicemail-detection instruction in the assistant's system prompt:

```json title="API Configuration"
{
  "model": {
    "provider": "openai",
    "model": "gpt-4o",
    "messages": [
      {
        "type": "system",
        "content": "You are a sales representative for Acme Corp. If at any point you determine you're speaking to a voicemail system (greeting mentions 'unavailable', 'leave a message', 'voicemail', etc.), immediately use the leave_voicemail tool."
      }
    ],
    "tools": [
      {
        "type": "voicemail",
        "function": {
          "name": "leave_voicemail",
          "description": "Leave a voicemail message when you detect you've reached a voicemail system"
        },
        "messages": [
          {
            "type": "request-start",
            "content": "Hi, this is {{company}}. {{message}}. Please call us back at {{phone}}."
          }
        ]
      }
    ]
  }
}
```

The `messages` array under `model` is your assistant's system prompt, while the `messages` array under the tool is the voicemail script the tool speaks when invoked.

## Message configuration

### Assistant voicemail message

To reuse the same voicemail across an assistant without configuring the tool separately, leave the tool's `messages` empty and set `voicemailMessage` on the assistant:

```json title="API Configuration"
{
  "voicemailMessage": "Hi, sorry I missed you — please give us a call back at 555-0100.",
  "model": {
    "provider": "openai",
    "model": "gpt-4o",
    "messages": [
      {
        "type": "system",
        "content": "You are an outbound sales agent. If you detect a voicemail system, use the leave_voicemail tool to leave the configured message."
      }
    ],
    "tools": [
      {
        "type": "voicemail",
        "function": {
          "name": "leave_voicemail",
          "description": "Leave a voicemail when you detect a voicemail system"
        },
        "messages": []
      }
    ]
  }
}
```

### Custom script mode

For custom-script mode, define the voicemail message inline:

```json title="API Configuration"
{
  "model": {
    "provider": "openai",
    "model": "gpt-4o",
    "messages": [
      {
        "type": "system",
        "content": "You are a sales representative for Acme Corp. If at any point you determine you've reached a voicemail system, immediately use the leave_voicemail tool to deliver the configured message."
      }
    ],
    "tools": [
      {
        "type": "voicemail",
        "function": {
          "name": "leave_voicemail",
          "description": "Leave a voicemail message when you detect you've reached a voicemail system"
        },
        "messages": [
          {
            "type": "request-start",
            "content": "Hi, this is {{company}}. {{message}}. Please call us back at {{phone}}."
          }
        ]
      }
    ]
  }
}
```

You can set a hardcoded message, or use template variables like `{{company}}`, `{{message}}`, and `{{phone}}` that are substituted at call time. See [Variables](/assistants/dynamic-variables) for how to pass values.

### Skip mode (silent end-call)

To silently terminate the call on voicemail, leave the tool's `messages` array empty and clear `voicemailMessage` on the assistant:

```json title="API Configuration"
{
  "model": {
    "provider": "openai",
    "model": "gpt-4o",
    "messages": [
      {
        "type": "system",
        "content": "You are calling prospects. If at any point you determine you've reached a voicemail system or auto-attendant (greeting mentions 'unavailable', 'leave a message', 'voicemail', 'press 1 for', etc.), immediately invoke the end_on_voicemail tool. Do not leave a message."
      }
    ],
    "tools": [
      {
        "type": "voicemail",
        "function": {
          "name": "end_on_voicemail",
          "description": "Silently end the call when you detect a voicemail system"
        },
        "messages": []
      }
    ]
  }
}
```

Use this mode for outbound outreach where the value is a live conversation and a missed voicemail is fine — silent termination keeps the call short and avoids the cost of running it to the max-duration cap.

### Pre-recorded audio messages

For consistent quality and pronunciation, use pre-recorded audio files by providing the URL in the `content` field:

```json title="API Configuration"
{
  "model": {
    "provider": "openai",
    "model": "gpt-4o",
    "messages": [
      {
        "type": "system",
        "content": "You are a sales representative for Acme Corp. If you detect a voicemail system, use the leave_voicemail tool to play our pre-recorded message."
      }
    ],
    "tools": [
      {
        "type": "voicemail",
        "function": {
          "name": "leave_voicemail",
          "description": "Leave a pre-recorded voicemail message"
        },
        "messages": [
          {
            "type": "request-start",
            "content": "https://example.com/voicemail.mp3"
          }
        ]
      }
    ]
  }
}
```

Pre-recorded audio messages are ideal for brand-specific messaging or when you
need precise pronunciation of phone numbers, website URLs, or company names.
Supported formats: `.wav` and `.mp3` files.

## 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.)            |

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

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

* Learn about other [default tools](/tools/default-tools)
* See how to create [custom tools](/tools/custom-tools) for your specific needs