Voicemail Tool

Overview

The voicemail tool gives your assistant direct control over what happens when it reaches a voicemail system. Unlike automatic voicemail detection, which operates independently of your assistant, this tool lets your assistant decide when it’s hit voicemail and then either leave a configured message or silently end the call — depending on how you’ve set it up.

Key benefits:

• Maximum flexibility — assistant decides when to invoke the tool, and you decide what happens when it does
• Customizable — use template variables to personalize voicemails per call
• Cost-effective — only triggers when needed
• Simple integration — works like other built-in tools

How it works

When you add the voicemail tool to your assistant:

1. Your assistant listens for voicemail indicators (greetings mentioning “unavailable”, “leave a message”, etc.)
2. Upon detecting voicemail, the assistant calls the tool
3. Depending on how you’ve configured the tool, it either delivers your configured message or skips speaking entirely
4. The call ends automatically

Voicemail behavior modes

When you configure the voicemail tool, you choose what the caller hears once voicemail is detected:

How the modes map to the underlying fields

Two fields work together to drive these modes: the tool’s messages array (which can hold a request-start message with optional template variables) and the assistant-level voicemailMessage property. The dashboard radio buttons orchestrate these for you, but if you’re configuring via the API, set the fields directly:

Configuration

Add the voicemail tool to your assistant and configure your system prompt to invoke it when voicemail is detected.

Message configuration

Assistant voicemail message

To reuse the same voicemail across an assistant without configuring the tool separately, leave the tool’s messages empty and set voicemailMessage on the assistant:

1
{
2
  "voicemailMessage": "Hi, sorry I missed you — please give us a call back at 555-0100.",
3
  "model": {
4
    "provider": "openai",
5
    "model": "gpt-4o",
6
    "messages": [
7
      {
8
        "type": "system",
9
        "content": "You are an outbound sales agent. If you detect a voicemail system, use the leave_voicemail tool to leave the configured message."
10
      }
11
    ],
12
    "tools": [
13
      {
14
        "type": "voicemail",
15
        "function": {
16
          "name": "leave_voicemail",
17
          "description": "Leave a voicemail when you detect a voicemail system"
18
        },
19
        "messages": []
20
      }
21
    ]
22
  }
23
}

Custom script mode

For custom-script mode, define the voicemail message inline:

1
{
2
  "model": {
3
    "provider": "openai",
4
    "model": "gpt-4o",
5
    "messages": [
6
      {
7
        "type": "system",
8
        "content": "You are a sales representative for Acme Corp. If at any point you determine you've reached a voicemail system, immediately use the leave_voicemail tool to deliver the configured message."
9
      }
10
    ],
11
    "tools": [
12
      {
13
        "type": "voicemail",
14
        "function": {
15
          "name": "leave_voicemail",
16
          "description": "Leave a voicemail message when you detect you've reached a voicemail system"
17
        },
18
        "messages": [
19
          {
20
            "type": "request-start",
21
            "content": "Hi, this is {{company}}. {{message}}. Please call us back at {{phone}}."
22
          }
23
        ]
24
      }
25
    ]
26
  }
27
}

You can set a hardcoded message, or use template variables like {{company}}, {{message}}, and {{phone}} that are substituted at call time. See Variables for how to pass values.

Skip mode (silent end-call)

To silently terminate the call on voicemail, leave the tool’s messages array empty and clear voicemailMessage on the assistant:

1
{
2
  "model": {
3
    "provider": "openai",
4
    "model": "gpt-4o",
5
    "messages": [
6
      {
7
        "type": "system",
8
        "content": "You are calling prospects. If at any point you determine you've reached a voicemail system or auto-attendant (greeting mentions 'unavailable', 'leave a message', 'voicemail', 'press 1 for', etc.), immediately invoke the end_on_voicemail tool. Do not leave a message."
9
      }
10
    ],
11
    "tools": [
12
      {
13
        "type": "voicemail",
14
        "function": {
15
          "name": "end_on_voicemail",
16
          "description": "Silently end the call when you detect a voicemail system"
17
        },
18
        "messages": []
19
      }
20
    ]
21
  }
22
}

Use this mode for outbound outreach where the value is a live conversation and a missed voicemail is fine — silent termination keeps the call short and avoids the cost of running it to the max-duration cap.

Pre-recorded audio messages

For consistent quality and pronunciation, use pre-recorded audio files by providing the URL in the content field:

1
{
2
  "model": {
3
    "provider": "openai",
4
    "model": "gpt-4o",
5
    "messages": [
6
      {
7
        "type": "system",
8
        "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."
9
      }
10
    ],
11
    "tools": [
12
      {
13
        "type": "voicemail",
14
        "function": {
15
          "name": "leave_voicemail",
16
          "description": "Leave a pre-recorded voicemail message"
17
        },
18
        "messages": [
19
          {
20
            "type": "request-start",
21
            "content": "https://example.com/voicemail.mp3"
22
          }
23
        ]
24
      }
25
    ]
26
  }
27
}

Best practices

Detection prompting

Be specific about voicemail indicators in your system prompt:

• “unavailable”
• “leave a message”
• “voicemail”
• “at the tone”
• “beep”

For auto-attendants and IVR menus, add cues like:

• “press 1 for…”
• “for a list of departments”
• “if you know your party’s extension”

Message structure

Keep voicemail messages:

• Brief — under 30 seconds
• Clear — state name, company, and purpose
• Actionable — include callback number or next steps
• Professional — match your brand voice

Error handling

Consider edge cases:

• Long voicemail greetings
• Voicemail box full scenarios
• Systems requiring keypad input
• Auto-attendants that loop their menu

Voicemail tool vs. automatic detection

Common use cases

• Sales outreach — personalized follow-up messages
• Appointment reminders — leave detailed appointment information
• Customer service — callback scheduling with ticket numbers
• Lead qualification — leave targeted messages based on lead data
• Outbound prospecting (no message) — cleanly terminate calls that hit voicemail when your strategy depends on live conversation

Next steps

• Learn about other default tools
• See how to create custom tools for your specific needs