Voicemail Detection

Voice Mail Detection automatically detects when outbound calls are routed to voicemail and triggers a callback so your agent can leave a message or end the call, preventing the agent from speaking or waiting unnecessarily. Voice Mail Detection lets you:

Detect voicemail systems automatically.
Control how your agent responds.
End calls cleanly after voicemail handling.

Setup

Import VoiceMailDetector, attach it to your agent’s Pipeline, and register a callback that defines how voicemail should be handled. The runtime runs the detector and fires your callback when the session is started with zrt.invoke().

To set up outbound calling and routing rules, check out Handling Calls.

from zrt import Pipeline, VoiceMailDetector
from zrt.plugins import OpenAILLM, DeepgramSTT, CartesiaTTS, TurnDetector
from zrt.inference import AICousticsDenoise

async def voice_mail_callback(event):
    # event: the detection payload (e.g. transcript, confidence)
    await agent.session.say("We tried to reach you. Please call us back.")

voicemail = VoiceMailDetector(
    llm=OpenAILLM(),
    callback=voice_mail_callback,
    duration=5,
    auto_hangup=True,
)

pipeline = Pipeline(
    stt=DeepgramSTT(),
    llm=OpenAILLM(),
    tts=CartesiaTTS(),
    turn_detector=TurnDetector(model="echo-large"),
    voice_mail_detector=voicemail,
    denoise=AICousticsDenoise(model_id="quail-vf-2.2-l-16khz"),
)

How it works

The detector buffers the opening speech on an outbound call for duration seconds, then asks the llm to classify the transcript as a human or a voicemail greeting (a one-word yes/no). If it’s classified as voicemail, your callback runs so you can leave a message or hang up cleanly.

Parameters

Parameter	Type	Default	Description
`llm`	`LLM`	required	LLM instance used to classify the opening transcript as human vs. voicemail.
`callback`	`Callable`	required	Called when a voicemail is detected, with the detection event payload (transcript, confidence). Sync or async.
`duration`	`float` (seconds)	`2.0`	How long to buffer the opening speech before classifying.
`custom_prompt`	`str`	`None`	Override the built-in classifier system prompt for custom voicemail-detection logic.
`auto_hangup`	`bool`	`False`	Automatically end the session when a voicemail is detected.
`detection_threshold`	`float`	`1.0`	Confidence threshold for gating detection.

Get started

Modalities

Configure Pipeline

Tools and Capabilities

Turn Detection and Interruptions

Telephony Agents

Context Management

Observability and Monitoring

Setup

How it works

Parameters

What’s Next

DTMF Events

Call Transfer

References

SDK Reference

Voice Mail Detector

​Setup

​How it works

​Parameters

​What’s Next

DTMF Events

Call Transfer

​References

​SDK Reference

Voice Mail Detector

Setup

How it works

Parameters

What’s Next

References

SDK Reference