Voicemail Detection

When you’re running outbound voice agents, voicemails are a reality — but wasting time or missing opportunities because of them shouldn’t be.

Vapi’s voicemail detection gives you faster, smarter, and more flexible handling of voicemail events, so you can keep your calls efficient, responsive, and professional.

Why Voicemail Detection Matters

• 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.

Detection Options

You can choose between several detection methods — but not all are created equal:

Vapi Voicemail Detection

With Vapi Voicemail Detection, your assistant will:

• 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 — support interruption handling and false positive protection.

How to Configure It

On the Assistants tab, you’ll find the Voicemail Detection section:

You can choose your preferred detection provider:

• Vapi (default)
• Google
• OpenAI
• Twilio
• Tool-based (beta)

Advanced Configuration Options

For each detection method, you can fine-tune the following parameters:

These settings allow you to balance:

• Speed (how quickly voicemail is detected)
• Accuracy (reducing false positives)
• Cost (fewer detection attempts = lower API costs)

Important: beepMaxAwaitSeconds Configuration

The beepMaxAwaitSeconds parameter is critical for voicemail message timing:

• What it does: Sets the maximum time from call start to wait for a voicemail beep before the bot starts speaking its message
• If beep detected early: Bot speaks immediately after the beep (optimal)
• If no beep by timeout: Bot starts speaking the voicemail message anyway
• Risk of low values: Bot may start speaking before the actual beep and get cut off by the voicemail system

Recommended values:

• Conservative: 25-30 seconds (default: 30)
• Aggressive: 15-20 seconds (requires testing with your specific voicemail patterns)
• Range: 0-60 seconds

How Vapi Detection Works

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)

This hybrid approach means less call delay, fewer mistakes, and a much more natural call experience.

Complete Configuration Examples

Here are complete assistant configurations for different real-world scenarios:

Sales Outreach Assistant

This configuration optimizes for fast detection and professional voicemail delivery in sales scenarios:

1
{
2
  "name": "Sales Outreach Assistant",
3
  "voice": {
4
    "provider": "vapi",
5
    "voiceId": "Paige"
6
  },
7
  "model": {
8
    "model": "gpt-4o",
9
    "messages": [
10
      {
11
        "role": "system",
12
        "content": "You are a professional sales representative calling prospects about our software solutions. Be friendly, concise, and respect their time. If you reach voicemail, keep your message under 30 seconds."
13
      }
14
    ],
15
    "provider": "openai",
16
    "temperature": 0.3
17
  },
18
  "firstMessage": "Hi! This is Sarah from TechSolutions. I hope I'm catching you at a good time.",
19
  "voicemailMessage": "Hi, this is Sarah from TechSolutions. I'm calling about the software demo you requested. I'd love to show you how we can help streamline your operations and save you time. Please call me back at 555-0123, or I'll try you again tomorrow. Thanks!",
20
  "endCallMessage": "Thanks for your time. Have a great day!",
21
  "transcriber": {
22
    "model": "nova-2",
23
    "language": "en",
24
    "provider": "deepgram",
25
    "smartFormat": true
26
  },
27
  "firstMessageMode": "assistant-waits-for-user",
28
  "voicemailDetection": {
29
    "provider": "vapi",
30
    "backoffPlan": {
31
      "maxRetries": 5,
32
      "startAtSeconds": 2,
33
      "frequencySeconds": 2.5
34
    },
35
    "beepMaxAwaitSeconds": 12
36
  },
37
  "messagePlan": {
38
    "idleMessages": ["Hello? Are you still there?"],
39
    "idleTimeoutSeconds": 8
40
  },
41
  "startSpeakingPlan": {
42
    "waitSeconds": 0.7,
43
    "smartEndpointingPlan": {
44
      "provider": "livekit",
45
      "waitFunction": "2000 / (1 + exp(-10 * (x - 0.5)))"
46
    }
47
  },
48
  "stopSpeakingPlan": {
49
    "numWords": 2,
50
    "backoffSeconds": 0.8
51
  },
52
  "backgroundDenoisingEnabled": true
53
}

Customer Support Callback Assistant

Optimized for high-accuracy detection and detailed voicemail messages:

1
{
2
  "name": "Customer Support Assistant",
3
  "voice": {
4
    "provider": "vapi",
5
    "voiceId": "Elliot"
6
  },
7
  "model": {
8
    "model": "gpt-4o",
9
    "messages": [
10
      {
11
        "role": "system",
12
        "content": "You are a customer support representative calling customers back about their support tickets. Be empathetic, helpful, and provide clear next steps. Always reference their ticket number."
13
      }
14
    ],
15
    "provider": "openai",
16
    "temperature": 0.2
17
  },
18
  "firstMessage": "Hello! This is Maya from Customer Support. I'm calling back about your recent support request.",
19
  "voicemailMessage": "Hi, this is Maya from Customer Support calling about ticket #{{ticketNumber}}. I have some updates on your issue and want to help resolve this quickly. Please call me back at 1-800-SUPPORT, or reply to your support email and I'll get back to you within 2 hours. Thanks!",
20
  "voicemailDetection": {
21
    "provider": "google",
22
    "backoffPlan": {
23
      "maxRetries": 8,
24
      "startAtSeconds": 3,
25
      "frequencySeconds": 3
26
    },
27
    "beepMaxAwaitSeconds": 20
28
  },
29
  "transcriber": {
30
    "model": "nova-2",
31
    "language": "en",
32
    "provider": "deepgram",
33
    "endpointing": 12,
34
    "smartFormat": true
35
  },
36
  "backgroundDenoisingEnabled": true
37
}

Appointment Reminder Assistant

Balanced configuration for appointment confirmations with fallback voicemail:

1
{
2
  "name": "Appointment Reminder Assistant",
3
  "voice": {
4
    "provider": "vapi",
5
    "voiceId": "Rohan"
6
  },
7
  "model": {
8
    "model": "gpt-4o",
9
    "messages": [
10
      {
11
        "role": "system",
12
        "content": "You are calling to remind patients about their upcoming appointments. Be warm, professional, and provide all necessary details including date, time, and preparation instructions."
13
      }
14
    ],
15
    "provider": "openai",
16
    "temperature": 0.1
17
  },
18
  "firstMessage": "Hi! This is Ryan calling from Dr. Smith's office about your upcoming appointment.",
19
  "voicemailMessage": "Hi, this is Ryan from Dr. Smith's office calling to remind you about your appointment on {{appointmentDate}} at {{appointmentTime}}. Please arrive 15 minutes early and bring your insurance card. If you need to reschedule, please call us at 555-CLINIC. Thanks!",
20
  "voicemailDetection": {
21
    "provider": "vapi",
22
    "backoffPlan": {
23
      "maxRetries": 6,
24
      "startAtSeconds": 2.5,
25
      "frequencySeconds": 2.5
26
    },
27
    "beepMaxAwaitSeconds": 15
28
  },
29
  "transcriber": {
30
    "model": "nova-2",
31
    "language": "en",
32
    "provider": "deepgram",
33
    "endpointing": 10,
34
    "smartFormat": true
35
  }
36
}

Provider-Specific Configurations

Vapi Provider (Recommended)

Best balance of speed and accuracy:

1
{
2
  "voicemailDetection": {
3
    "provider": "vapi",
4
    "backoffPlan": {
5
      "maxRetries": 5,
6
      "startAtSeconds": 2,
7
      "frequencySeconds": 2.5
8
    },
9
    "beepMaxAwaitSeconds": 12
10
  }
11
}

Google Provider

Maximum accuracy for critical calls (best with audio detection):

1
{
2
  "voicemailDetection": {
3
    "provider": "google",
4
    "backoffPlan": {
5
      "maxRetries": 8,
6
      "startAtSeconds": 3,
7
      "frequencySeconds": 3
8
    },
9
    "beepMaxAwaitSeconds": 20
10
  }
11
}

OpenAI Provider

High accuracy with cost consideration (best with transcript detection):

1
{
2
  "voicemailDetection": {
3
    "provider": "openai",
4
    "type": "transcript",
5
    "backoffPlan": {
6
      "maxRetries": 6,
7
      "startAtSeconds": 2.5,
8
      "frequencySeconds": 3
9
    },
10
    "beepMaxAwaitSeconds": 15
11
  }
12
}

Detection Types

Choose between two detection methods based on provider performance:

Pre-recorded Audio Messages

Instead of text-to-speech, you can use pre-recorded audio files for your voicemail messages. Simply provide the URL to your audio file in the voicemailMessage property:

1
{
2
  "name": "Sales Assistant with Audio Message",
3
  "model": {
4
    "provider": "openai",
5
    "model": "gpt-4o"
6
  },
7
  "voicemailDetection": {
8
    "provider": "vapi"
9
  },
10
  "voicemailMessage": "https://example.com/sales-voicemail.mp3"
11
}

Supported formats: .wav and .mp3 files

Disabling Voicemail Detection

To completely disable voicemail detection for your assistant, set the voicemailDetection property to "off":

1
{
2
  "name": "Assistant Without Voicemail Detection",
3
  "voicemailDetection": "off",
4
  "model": {
5
    "provider": "openai",
6
    "model": "gpt-4o"
7
  }
8
}

Configuration Best Practices

Tuning for Different Scenarios

Cost Optimization Tips

1. Lower maxRetries for high-volume campaigns
2. Increase startAtSeconds to reduce false positives
3. Use Vapi provider for best cost-to-accuracy ratio
4. Tune beepMaxAwaitSeconds carefully - too low causes cut-off messages, too high delays voicemail delivery

Accuracy Optimization Tips

1. Use Google provider for maximum accuracy
2. Increase maxRetries for important calls
3. Lower startAtSeconds for faster detection
4. Tune frequencySeconds based on your voicemail patterns (minimum 2.5 seconds)

Troubleshooting Common Issues

False Positives (Detecting voicemail when human answers)

Symptoms: Assistant leaves voicemail message when human picks up

Solutions:

• Increase startAtSeconds to 3-4 seconds
• Switch to Google or OpenAI provider
• Increase frequencySeconds to 3-4 seconds

1
{
2
  "voicemailDetection": {
3
    "provider": "google",
4
    "backoffPlan": {
5
      "startAtSeconds": 3.5,
6
      "frequencySeconds": 3.5,
7
      "maxRetries": 6
8
    }
9
  }
10
}

Missed Voicemails (Not detecting actual voicemail)

Symptoms: Assistant continues talking to voicemail recording

Solutions:

• Decrease startAtSeconds to 1-2 seconds
• Increase maxRetries to 8-10
• Keep frequencySeconds at minimum value (2.5 seconds)

1
{
2
  "voicemailDetection": {
3
    "provider": "vapi",
4
    "backoffPlan": {
5
      "startAtSeconds": 1.5,
6
      "frequencySeconds": 2.5,
7
      "maxRetries": 8
8
    }
9
  }
10
}

Slow Detection

Symptoms: Takes too long to detect voicemail

Solutions:

• Use Vapi provider for fastest detection
• Decrease startAtSeconds (frequencySeconds minimum is 2.5)
• Ensure good audio quality

1
{
2
  "voicemailDetection": {
3
    "provider": "vapi",
4
    "backoffPlan": {
5
      "startAtSeconds": 1,
6
      "frequencySeconds": 2.5,
7
      "maxRetries": 6
8
    }
9
  }
10
}

By using Vapi’s detection system, you’ll avoid the common pitfalls of voicemail detection, while creating a faster, smarter, and more professional experience for your users.

Related Documentation

• Voicemail Tool - Alternative assistant-controlled voicemail approach for maximum flexibility