Voicemail tool

Overview

The Voicemail tool gives your assistant direct control over what happens when it reaches a voicemail system. Unlike automatic 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:

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

This approach differs from automatic 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 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
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

Configure the Voicemail tool: create the tool, attach it to an assistant, and set its message
Learn about other built-in tools
See how to create Function tools for your specific needs