Pre-Recorded Voicemail Messages

Overview

The voicemail tool can play a pre-recorded audio file instead of generating a spoken message with text-to-speech when a voicemail system is detected. This gives you consistent, exact wording every time the tool fires, since the message is a produced audio file rather than a synthesized voice.

This page covers the pre-recorded audio option specifically. If you're looking for the separate, fully automatic voicemail detection feature, see Voicemail Detection instead.

When the assistant recognizes that it has reached a voicemail system, it invokes the voicemail tool. Unlike automatic voicemail detection, which is driven by the platform's own detection engine, this approach relies on the assistant itself recognizing voicemail cues from the conversation and calling the tool. Once called, the tool plays the audio file you've configured directly, and the call ends automatically once playback finishes.

Provide the URL of your audio file in the content field of the tool's request-start message. Add the tool to your assistant's tools array:

{
  "model": {
    "provider": "openai",
    "model": "gpt-4o",
    "messages": [
      {
        "type": "system",
        "content": "You are a sales representative for Acme Corp. If you detect a voicemail system, use the leave_voicemail tool to play our pre-recorded message."
      }
    ],
    "tools": [
      {
        "type": "voicemail",
        "function": {
          "name": "leave_voicemail",
          "description": "Leave a pre-recorded voicemail message"
        },
        "messages": [
          {
            "type": "request-start",
            "content": "https://assets.sulus.ai/voicemail.mp3"
          }
        ]
      }
    ]
  }
}

Pre-recorded audio messages support .wav and .mp3 file formats. Hosting the file at a stable, publicly reachable URL is required, since the tool fetches and plays it directly at call time.

This option is well suited to brand-specific messaging that needs consistent tone, exact pronunciation of phone numbers, URLs, or company names that text-to-speech may mispronounce, and scenarios with regulatory requirements for precise, pre-approved wording.

Because detection here is driven by the assistant reading conversational cues rather than by a dedicated detection engine, your system prompt must explicitly tell the assistant which indicators mean it has reached a voicemail system. Be specific about phrases such as:

• "unavailable"
• "leave a message"
• "voicemail"
• "at the tone"
• "beep"

Without this guidance, the assistant has no reliable way to recognize a voicemail system and decide to invoke the tool.

Do not combine this assistant-driven voicemail tool with the platform's automatic voicemail detection on the same call. Running both at once causes false positives, since two independent mechanisms are each trying to decide whether a voicemail system has answered.

The call ends automatically once the pre-recorded audio finishes playing — there is no further conversation after the message plays.

For the separate automatic-detection feature, including provider options and advanced timing configuration, see Voicemail Detection.