Voicemail Detection

Detect voicemail systems on outbound calls and optionally leave a pre-configured message.

Technical documentation for the voicemail_detection feature.

Overview

Voicemail Detection is a feature for outbound calls only that allows the AI assistant to detect when it has reached a voicemail system instead of a live person. When voicemail is detected, the assistant can either:

Leave a pre-configured voicemail message, or
Hang up immediately without leaving a message

This prevents wasted assistant time talking to voicemail systems and enables targeted voicemail campaigns.

Configuration

Assistant Schema

{
  "voicemail_detection": true,
  "voicemail_message": "Hello, this is a message from Acme Corp. Please call us back at 555-1234. Thank you."
}

Field	Type	Default	Description
`voicemail_detection`	boolean	`false`	Enable/disable voicemail detection
`voicemail_message`	string	`null`	Message to leave on voicemail. If null/empty, assistant hangs up without leaving a message

How It Works

Detection Method

Voicemail detection uses speech-to-text analysis of the first utterance from the called party. When the recipient answers, their greeting is transcribed and analyzed for voicemail indicators.

Voicemail Indicators

The system checks for these keywords/phrases in the initial greeting:

voicemail_indicators = [
    "voicemail", "leave a message", "please record",
    "unavailable", "not available", "not here",
    "after the tone", "after the beep", "press star",
    "speak your message", "call back later",
    "mailbox", "beep", "message"
]

Supports multiple languages including English and Dutch.

Detection Flow

[Outbound Call] → [Recipient Answers] → [First Utterance] → [STT Transcription]
                                                                    ↓
                                              [Check for Voicemail Indicators]
                                                          ↓                ↓
                                                   [No Match]        [Match Found]
                                                        ↓                  ↓
                                              [Continue Call]    [Voicemail Detected]
                                                                          ↓
                                                         [Has voicemail_message?]
                                                          ↓                ↓
                                                        [No]            [Yes]
                                                          ↓                ↓
                                                    [Hang Up]    [Leave Message → Hang Up]

One-Time Check

Detection only occurs on the first user utterance. Once the check is done (match or no match), voicemail detection is complete for that call. This prevents false positives during normal conversation.

Behavior

User speaks - Recipient answers and speaks first
First utterance check - System checks if this is the first time they spoke
Keyword scan - Transcription is analyzed for voicemail indicators
Detection triggered - If match found, voicemail is detected
Leave message - If voicemail_message is set, assistant speaks it
Wait for playback - System waits for message to finish playing
End call - Call is automatically terminated

Message Playback

The system automatically waits for the voicemail message to finish playing before ending the call. The timing is estimated based on message length and typical speech rate.

Use Cases

Campaign Calls

Perfect for outbound campaigns where you want to:

Leave consistent voicemail messages
Track voicemail vs. live answer rates
Avoid wasting assistant resources on voicemail systems

Appointment Reminders

Leave reminder message if voicemail reached
Transfer to booking system if live person answers

Sales Outreach

Leave callback request on voicemail
Engage in conversation if live person answers

Limitations

Detection Accuracy

Not 100% accurate: Relies on keyword matching in transcribed speech
Language dependent: Indicators are primarily English/Dutch
False negatives: Some voicemail greetings may not contain keywords
False positives: Rare, but possible if person says "leave a message" naturally

Speech-Only Detection

The system does not detect the voicemail beep tone. It relies solely on speech analysis of the greeting. This means:

Detection works by analyzing the spoken greeting
Some voicemail systems with unusual greetings may not be detected

Outbound Only

Voicemail detection is only available for outbound calls. The feature is automatically disabled for inbound calls.

Webhook Events

Status Update

When voicemail is detected:

{
  "message": {
    "type": "status-update",
    "call": {
      "status": "in-progress"
    }
  }
}

Note: There is no special "voicemail-detected" status. The call remains "in-progress" until it ends.

End of Call Report

{
  "message": {
    "type": "end-of-call-report",
    "call": {
      "status": "ended"
    },
    "summary": "Voicemail detected. Left message: Hello, this is...",
    "messages": [
      {"role": "user", "content": "You have reached the voicemail of..."},
      {"role": "assistant", "content": "Hello, this is a message from..."}
    ]
  }
}

The transcript will show the voicemail greeting (user) and the message left (assistant).

Configuration Examples

Leave Voicemail Message

{
  "voicemail_detection": true,
  "voicemail_message": "Hello, this is Sarah from Acme Corp calling about your recent inquiry. Please call us back at 555-1234 at your earliest convenience. Thank you and have a great day."
}

Hang Up Without Message

{
  "voicemail_detection": true,
  "voicemail_message": null
}

Or simply omit voicemail_message:

{
  "voicemail_detection": true
}

Disabled (Default)

{
  "voicemail_detection": false
}

Allows voicemail detection to analyze the greeting
More natural for outbound calls (recipient says "hello" first)

With Campaign Calls

When using campaigns with lead context:

voicemail_detection and voicemail_message come from the assistant config
Lead context is injected into the system prompt for live conversations
Voicemail message is static (not personalized with lead data)

Troubleshooting

Voicemail Not Being Detected

Verify voicemail_detection: true is set in assistant configuration
Check if the voicemail greeting contains any of the indicator keywords listed above
Review the call transcript to see what was detected in the first utterance
Consider that some voicemail systems may use greetings without standard indicators

Message Not Being Left

Verify voicemail_message is set and not empty in assistant configuration
Ensure your TTS configuration is working correctly
Check the call transcript to confirm voicemail was detected

Call Not Ending After Voicemail

Review the end-of-call-report webhook for error details
Verify the assistant has proper permissions and configuration
Check that the call didn't exceed max_duration_seconds separately

Future Improvements

Potential enhancements (not currently implemented):

Beep detection: Use audio analysis to detect voicemail tone
Configurable indicators: Allow custom keywords per assistant/language
Personalized voicemail: Template variables in voicemail_message
Voicemail status: Dedicated call status for voicemail detection
Retry logic: Option to call back later if voicemail reached