You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Voicemail is basically a digital answering machine. When you can’t pick up, callers can leave a message so you don’t miss anything important. It’s especially handy if you’re in a meeting, driving, or just can’t get to the phone in time.
6
+
# Voicemail Detection
7
7
8
-
### **The Main Problem**
8
+
When you're running outbound voice agents, voicemails are a reality — but wasting time or missing opportunities because of them shouldn't be.
9
9
10
-
If a lot of your calls are landing in voicemail, you could be spending too much time and money on calls that never connect to a real person. This leads to wasted resources, and sometimes missed business opportunities.
10
+
**Vapi's updated voicemail detection system** gives you faster, smarter, and more flexible handling of voicemail events, so you can keep your calls efficient, responsive, and professional.
11
11
12
-
###**The Solution: Early Voicemail Detection**
12
+
## **Why Voicemail Detection Matters**
13
13
14
-
By detecting voicemail right away, your Vapi Assistant can either hang up (if leaving a message isn’t necessary) or smoothly play a recorded message. This cuts down on useless call time and makes your entire call flow more efficient.
14
+
-**Save time** by avoiding long waits on unanswered calls.
15
+
-**Optimize costs** by cutting down on wasted minutes.
16
+
-**Improve UX** by ensuring your agent behaves naturally when encountering voicemail greetings.
17
+
-**Boost response rates** by leaving cleaner, more intentional voicemail messages.
15
18
16
-
## **Two Ways to Detect Voicemail**
17
-
18
-
### **1. Using Twilio’s Voicemail Detection**
19
-
20
-
Twilio has built-in features to detect when a machine picks up. You configure these settings in your Vapi Assistant so it knows when a voicemail system has answered instead of a live person.
21
-
22
-
```jsx
23
-
voicemailDetection: {
24
-
provider:"twilio",
25
-
voicemailDetectionTypes: [
26
-
"machine_start",
27
-
"machine_end_beep",
28
-
"machine_end_silence",
29
-
"unknown",
30
-
"machine_end_other"
31
-
],
32
-
enabled:true,
33
-
machineDetectionTimeout:15,
34
-
machineDetectionSpeechThreshold:2500,
35
-
machineDetectionSpeechEndThreshold:2050,
36
-
machineDetectionSilenceTimeout:2000
37
-
}
38
-
39
-
```
40
-
41
-
-**provider**: Tells Vapi to use Twilio’s system.
42
-
-**voicemailDetectionTypes**: Defines the events that mean “voicemail.”
43
-
-**machineDetectionTimeout**: How many seconds to wait to confirm a machine.
44
-
- The other settings let you fine-tune how quickly or accurately Twilio identifies a machine based on speech or silence.
| machineDetectionSpeechThreshold | number | 1000–6000 ms | 2400 ms |
52
-
| machineDetectionSpeechEndThreshold | number | 500–5000 ms | 1200 ms |
53
-
| machineDetectionSilenceTimeout | number | 2000–10000 ms | 5000 ms |
54
-
55
-
### **2. Using VAPI’s Built-In Voicemail Tool**
19
+
---
56
20
57
-
Vapi also has an LLM-powered tool that listens for typical voicemail greetings or prompts in the call’s audio transcription. If you prefer an approach that relies more on phrasing and context clues, this is a great option.
21
+
## **Today's Detection Options**
58
22
59
-
```jsx
60
-
{
61
-
...yourExistingSettings,
62
-
"model": {
63
-
"tools": [{ type:"voicemail" }]
64
-
}
65
-
}
23
+
You can now choose between several detection methods — but not all are created equal:
|**Google**| Very good accuracy, reliable | Slightly longer detection time than Vapi | ✅ Recommended |
29
+
|**OpenAI**| High accuracy, flexible phrasing | Higher cost | ✅ Good option if budget allows |
30
+
|**Twilio** (legacy) | Very fast machine beep detection | Prone to false positives | ⚠️ Use only in special cases |
31
+
|**Vapi Voicemail Tool** (legacy) | Keyword-based detection in transcription | Slow, context-dependent | ⚠️ Use only if needed |
68
32
69
-
Here, `tools: [{ type: "voicemail" }]` signals that your Vapi Assistant should look for keywords or patterns indicating a voicemail greeting.
33
+
---
70
34
71
-
## **Combining Both Approaches**
35
+
## **New Default Behavior: Vapi Voicemail Detection**
72
36
73
-
For the best of both worlds, you can enable Twilio’s detection **and** the built-in voicemail tool at the same time:
37
+
With **Vapi Voicemail Detection**, your assistant will:
74
38
75
-
```jsx
76
-
{
77
-
...yourExistingSettings,
78
-
voicemailDetection: {
79
-
provider:"twilio",
80
-
voicemailDetectionTypes: [
81
-
"machine_start",
82
-
"machine_end_beep",
83
-
"unknown"
84
-
],
85
-
enabled:true,
86
-
machineDetectionTimeout:15
87
-
},
88
-
model: {
89
-
tools: [{ type:"voicemail" }]
90
-
}
91
-
}
39
+
-**Detect voicemail faster** (often within the first few seconds of the call).
40
+
-**Handle real-time pickups** gracefully — if a human picks up mid-voicemail, the agent will switch back naturally.
41
+
-**Interrupt the bot's first message** appropriately if voicemail is detected mid-sentence.
42
+
-**Minimize false positives** by combining audio analysis (beeps) and transcription intelligence.
92
43
93
-
```
44
+
All three providers — **Vapi, Google, and OpenAI** — now support **interruption handling** and **false positive protection**.
94
45
95
-
When one method doesn’t catch it, the other might—boosting your overall detection accuracy.
46
+
---
96
47
97
-
## **Tips for Better Voicemail Handling**
48
+
## **How to Configure It**
98
49
99
-
1.**Adjust Detection Timing**
50
+
On the **Assistants tab**, you'll find an updated Voicemail Detection section:
100
51
101
-
Lower `machineDetectionTimeout` (e.g., to 5 seconds) if you want the system to decide faster. But remember, shorter timeouts can lead to occasional false positives.
For each detection method, you can fine-tune the following parameters:
116
64
117
-
```
65
+
| Parameter | Description |
66
+
| :-------- | :---------- |
67
+
|**Initial Detection Delay**| How long to wait (in seconds) before starting voicemail detection |
68
+
|**Detection Retry Interval**| How frequently to check for voicemail (in seconds) |
69
+
|**Max Detection Retries**| Maximum number of detection attempts before stopping |
70
+
|**Max Voicemail Message Wait**| Maximum time to wait before leaving a message (even without beep detection) |
118
71
119
-
These values tweak how quickly Twilio “listens” for human speech or background silence.
72
+
These settings allow you to balance:
73
+
-**Speed** (how quickly voicemail is detected)
74
+
-**Accuracy** (reducing false positives)
75
+
-**Cost** (fewer detection attempts = lower API costs)
120
76
121
-
3.**Think Through Your Call Flow**
122
-
-**Give It Time**: If you’re leaving a message, you might want to increase `startSpeakingPlan.waitSeconds` so the detection has enough time before the tone.
123
-
-**firstMessageMode**: Setting it to `assistant-waits-for-user` can also give you smoother call handling—your assistant won’t barge in if someone unexpectedly picks up late
77
+
---
124
78
125
-
## **What Happens When a Call Ends?**
79
+
## **How Vapi Detection Works**
126
80
127
-
-**Detected Voicemail + No Message**: The call will end, and you’ll see a reason like `customer-did-not-answer`.
128
-
-**Detected Voicemail + Have a Message**: Your assistant leaves the recorded message, and the call ends with a reason like `voicemail`.
81
+
Vapi's detection engine combines:
82
+
-**Gemini model-based detection** (fast and highly accurate on common voicemail phrasing)
83
+
-**Twilio beep detection** (optional, for faster reaction to voicemail system beeps)
84
+
-**Real-time call monitoring** to react instantly if a human unexpectedly picks up
85
+
-**Continuous voicemail polling** during early call stages (detecting voicemail faster without waiting for a full timeout)
129
86
130
-
## **Testing and Next Steps**
87
+
This hybrid approach means **less call delay, fewer mistakes, and a much more natural call experience.**
131
88
132
-
1.**Make a Test Call**: Dial a known voicemail number and watch how quickly (and accurately) your Vapi Assistant identifies the machine.
133
-
2.**Tweak Settings**: Adjust your timeout and threshold values based on real-world performance.
134
-
3.**Repeat**: Keep testing until you’re confident your configuration is catching voicemail reliably without cutting off real people.
89
+
---
135
90
136
-
By following these steps, you’ll save time, improve call-handling efficiency, and ensure your system feels more professional. If you need to fine-tune or add new features later, you can always revisit these settings and make quick adjustments.
91
+
By switching to Vapi's new detection system, you'll avoid the common pitfalls of older voicemail detection, while creating a **faster, smarter, and more professional experience** for your users.
0 commit comments