AssistantsToolsVoicemail tool

Configure the Voicemail tool

Create the tool, attach it to an assistant, and author what it speaks in each behavior mode

Configuring the Voicemail tool takes two parts: create the tool and attach it to an assistant, then decide what the assistant does once it knows it has reached voicemail. You can do both in the Dashboard or through the API.

Configuration

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

  1. Go to Tools in the left nav and click Create Tool.
  2. Select Voicemail as the tool type.
  3. Give the tool a name and description. The description tells the LLM when to invoke the tool — keep it consistent with the voicemail-detection instruction you’ll add to your system prompt in step 7. Example: “Leave a voicemail message when you detect you’ve reached a voicemail system or auto-attendant.”
  4. Under Voicemail Script, choose a behavior mode: Use assistant voicemail message, Use custom script, or Skip speaking a voicemail. See Voicemail behavior modes for details.
  5. Save the tool.
  6. Attach the tool to your assistant: open the assistant, go to Tools, and add the Voicemail tool you just created.
  7. Add a voicemail-detection instruction to your assistant’s system prompt. Without this, the LLM won’t know when to call the tool. See Detection prompting for indicators to include.

Voicemail tool configuration

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:

API Configuration
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:

API Configuration
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:

API Configuration
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:

API Configuration
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}

Pre-recorded audio messages are ideal for brand-specific messaging or when you need precise pronunciation of phone numbers, website URLs, or company names. Supported formats: .wav and .mp3 files.