diff --git a/fern/calls/voicemail-detection.mdx b/fern/calls/voicemail-detection.mdx index d1f562b2..edbe7bb3 100644 --- a/fern/calls/voicemail-detection.mdx +++ b/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. diff --git a/fern/static/images/advanced-tab/vapi-voicemail-detection.png b/fern/static/images/advanced-tab/vapi-voicemail-detection.png new file mode 100644 index 00000000..5e73bab6 Binary files /dev/null and b/fern/static/images/advanced-tab/vapi-voicemail-detection.png differ