Voicemail detection

Technical documentation for the voicemail_detection feature.

Overview

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

Leave a pre-configured voicemail message, or

Hang up immediately without leaving a message

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

Configuration

Agent 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, agent 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:

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, agent 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 agent 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
}

Interaction with Other Features

With `autonomous_silence_handling`

Both can be enabled. Voicemail detection happens first (on initial greeting). If voicemail is not detected, silence handling activates during normal conversation.

With `first_message`

For outbound calls, the agent does not speak first - it waits for the recipient to answer and speak. This is intentional:

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 agent 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 agent 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 agent 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 agent 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 agent/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

Voicemail detection

Overview#

Configuration#

Agent Schema#

How It Works#

Detection Method#

Voicemail Indicators#

Detection Flow#

One-Time Check#

Behavior#

Message Playback#

Use Cases#

Campaign Calls#

Appointment Reminders#

Sales Outreach#

Limitations#

Detection Accuracy#

Speech-Only Detection#

Outbound Only#

Webhook Events#

Status Update#

End of Call Report#

Configuration Examples#

Leave Voicemail Message#

Hang Up Without Message#

Disabled (Default)#

Interaction with Other Features#

With autonomous_silence_handling#

With first_message#

With Campaign Calls#

Troubleshooting#

Voicemail Not Being Detected#

Message Not Being Left#

Call Not Ending After Voicemail#

Future Improvements#