VAP-5935

fern/calls/voicemail-detection.mdx

@@ -3,134 +3,89 @@ title: Voicemail Detection
 slug: calls/voicemail-detection
 ---
 
-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.
+# Voicemail Detection
 
-### **The Main Problem**
+When you're running outbound voice agents, voicemails are a reality — but wasting time or missing opportunities because of them shouldn't be.
 
-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.
+**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.
 
-### **The Solution: Early Voicemail Detection**
+## **Why Voicemail Detection Matters**
 
-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.
+- **Save time** by avoiding long waits on unanswered calls.
+- **Optimize costs** by cutting down on wasted minutes.
+- **Improve UX** by ensuring your agent behaves naturally when encountering voicemail greetings.
+- **Boost response rates** by leaving cleaner, more intentional voicemail messages.
 
-## **Two Ways to Detect Voicemail**
-
-### **1. Using Twilio’s Voicemail Detection**
-
-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.
-
-```jsx
-voicemailDetection: {
-  provider: "twilio",
-  voicemailDetectionTypes: [
-    "machine_start",
-    "machine_end_beep",
-    "machine_end_silence",
-    "unknown",
-    "machine_end_other"
-  ],
-  enabled: true,
-  machineDetectionTimeout: 15,
-  machineDetectionSpeechThreshold: 2500,
-  machineDetectionSpeechEndThreshold: 2050,
-  machineDetectionSilenceTimeout: 2000
-}
-
-```
-
-- **provider**: Tells Vapi to use Twilio’s system.
-- **voicemailDetectionTypes**: Defines the events that mean “voicemail.”
-- **machineDetectionTimeout**: How many seconds to wait to confirm a machine.
-- The other settings let you fine-tune how quickly or accurately Twilio identifies a machine based on speech or silence.
-
-#### Quick Reference
-
-| Setting                            | Type   | Valid Range   | Default  |
-| ---------------------------------- | ------ | ------------- | -------- |
-| machineDetectionTimeout            | number | 3 – 59 (sec)  | 30 (sec) |
-| machineDetectionSpeechThreshold    | number | 1000–6000 ms  | 2400 ms  |
-| machineDetectionSpeechEndThreshold | number | 500–5000 ms   | 1200 ms  |
-| machineDetectionSilenceTimeout     | number | 2000–10000 ms | 5000 ms  |
-
-### **2. Using VAPI’s Built-In Voicemail Tool**
+---
 
-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.
+## **Today's Detection Options**
 
-```jsx
-{
-  ...yourExistingSettings,
-  "model": {
-    "tools": [{ type: "voicemail" }]
-  }
-}
+You can now choose between several detection methods — but not all are created equal:
 
-```
+| Detection Method | Strengths | Weaknesses | Recommendation |
+| :--------------- | :-------- | :--------- | :------------- |
+| **Vapi (Recommended)** | Fast, accurate, gracefully handles interruptions | None significant | ✅ Strongly recommended |
+| **Google** | Very good accuracy, reliable | Slightly longer detection time than Vapi | ✅ Recommended |
+| **OpenAI** | High accuracy, flexible phrasing | Higher cost | ✅ Good option if budget allows |
+| **Twilio** (legacy) | Very fast machine beep detection | Prone to false positives | ⚠️ Use only in special cases |
+| **Vapi Voicemail Tool** (legacy) | Keyword-based detection in transcription | Slow, context-dependent | ⚠️ Use only if needed |
 
-Here, `tools: [{ type: "voicemail" }]` signals that your Vapi Assistant should look for keywords or patterns indicating a voicemail greeting.
+---
 
-## **Combining Both Approaches**
+## **New Default Behavior: Vapi Voicemail Detection**
 
-For the best of both worlds, you can enable Twilio’s detection **and** the built-in voicemail tool at the same time:
+With **Vapi Voicemail Detection**, your assistant will:
 
-```jsx
-{
-  ...yourExistingSettings,
-  voicemailDetection: {
-    provider: "twilio",
-    voicemailDetectionTypes: [
-      "machine_start",
-      "machine_end_beep",
-      "unknown"
-    ],
-    enabled: true,
-    machineDetectionTimeout: 15
-  },
-  model: {
-    tools: [{ type: "voicemail" }]
-  }
-}
+- **Detect voicemail faster** (often within the first few seconds of the call).
+- **Handle real-time pickups** gracefully — if a human picks up mid-voicemail, the agent will switch back naturally.
+- **Interrupt the bot's first message** appropriately if voicemail is detected mid-sentence.
+- **Minimize false positives** by combining audio analysis (beeps) and transcription intelligence.
 
-```
+All three providers — **Vapi, Google, and OpenAI** — now support **interruption handling** and **false positive protection**.
 
-When one method doesn’t catch it, the other might—boosting your overall detection accuracy.
+---
 
-## **Tips for Better Voicemail Handling**
+## **How to Configure It**
 
-1. **Adjust Detection Timing**
+On the **Assistants tab**, you'll find an updated Voicemail Detection section:
 
-   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.
+![Vapi Voicemail Detection Configuration](/static/images/advanced-tab/vapi-voicemail-detection.png)
 
-2. **Fine-Tune Speech and Silence Thresholds**
+You can choose your preferred detection provider:
+- **Vapi (default)**
+- **Google**
+- **OpenAI**
+- **Twilio**
+- **Tool-based (legacy)**
 
-   For example:
+## **Advanced Configuration Options**
 
-   ```jsx
-   {
-     "provider": "twilio",
-     "enabled": true,
-     "machineDetectionTimeout": 5,
-     "machineDetectionSpeechThreshold": 2400,
-     "machineDetectionSpeechEndThreshold": 1000,
-     "machineDetectionSilenceTimeout": 3000
-   }
+For each detection method, you can fine-tune the following parameters:
 
-   ```
+| Parameter | Description |
+| :-------- | :---------- |
+| **Initial Detection Delay** | How long to wait (in seconds) before starting voicemail detection |
+| **Detection Retry Interval** | How frequently to check for voicemail (in seconds) |
+| **Max Detection Retries** | Maximum number of detection attempts before stopping |
+| **Max Voicemail Message Wait** | Maximum time to wait before leaving a message (even without beep detection) |
 
-   These values tweak how quickly Twilio “listens” for human speech or background silence.
+These settings allow you to balance:
+- **Speed** (how quickly voicemail is detected)
+- **Accuracy** (reducing false positives)
+- **Cost** (fewer detection attempts = lower API costs)
 
-3. **Think Through Your Call Flow**
-   - **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.
-   - **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
+---
 
-## **What Happens When a Call Ends?**
+## **How Vapi Detection Works**
 
-- **Detected Voicemail + No Message**: The call will end, and you’ll see a reason like `customer-did-not-answer`.
-- **Detected Voicemail + Have a Message**: Your assistant leaves the recorded message, and the call ends with a reason like `voicemail`.
+Vapi's detection engine combines:
+- **Gemini model-based detection** (fast and highly accurate on common voicemail phrasing)
+- **Twilio beep detection** (optional, for faster reaction to voicemail system beeps)
+- **Real-time call monitoring** to react instantly if a human unexpectedly picks up
+- **Continuous voicemail polling** during early call stages (detecting voicemail faster without waiting for a full timeout)
 
-## **Testing and Next Steps**
+This hybrid approach means **less call delay, fewer mistakes, and a much more natural call experience.**
 
-1. **Make a Test Call**: Dial a known voicemail number and watch how quickly (and accurately) your Vapi Assistant identifies the machine.
-2. **Tweak Settings**: Adjust your timeout and threshold values based on real-world performance.
-3. **Repeat**: Keep testing until you’re confident your configuration is catching voicemail reliably without cutting off real people.
+---
 
-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.
+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.