Skip to content

Commit 95e0884

Browse files
ramsribramsrib
authored
Added voicemail tool docs (#626)
* Added voicemail tool docs * added to index
1 parent b4b73e1 commit 95e0884

File tree

2 files changed

+238
-0
lines changed

2 files changed

+238
-0
lines changed

‎fern/docs.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -172,6 +172,9 @@ navigation:
172172
- page: Built-in call tools
173173
path: tools/default-tools.mdx
174174
icon: fa-light fa-gear
175+
- page: Voicemail tool
176+
path: tools/voicemail-tool.mdx
177+
icon: fa-light fa-voicemail
175178
- page: Custom tools
176179
path: tools/custom-tools.mdx
177180
icon: fa-light fa-screwdriver-wrench

‎fern/tools/voicemail-tool.mdx‎

Lines changed: 235 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,235 @@
1+
---
2+
title: Voicemail Tool
3+
subtitle: Learn how to use the assistant-controlled voicemail tool for flexible voicemail handling
4+
slug: tools/voicemail-tool
5+
---
6+
7+
<Warning>
8+
**Beta Feature**: The voicemail tool is currently in beta. Features and behavior may change as we continue to improve this functionality based on user feedback.
9+
</Warning>
10+
11+
## Overview
12+
13+
The voicemail tool gives your assistant direct control over when and how to leave voicemail messages. Unlike [automatic voicemail detection](/calls/voicemail-detection), which operates independently of your assistant, this tool allows your assistant to decide when it's reached a voicemail system and leave a configured message.
14+
15+
**Key benefits:**
16+
- **Maximum flexibility** - Assistant decides when and what to say
17+
- **Cost-effective** - Only triggers when needed
18+
- **Context-aware** - Messages can be customized based on conversation
19+
- **Simple integration** - Works like other built-in tools
20+
21+
## How it works
22+
23+
When you add the voicemail tool to your assistant:
24+
25+
1. Your assistant listens for voicemail indicators (greetings mentioning "unavailable", "leave a message", etc.)
26+
2. Upon detecting voicemail, the assistant calls the tool
27+
3. The tool delivers your configured message
28+
4. The call ends automatically after message delivery
29+
30+
<Note>
31+
This approach differs from [automatic voicemail detection](/calls/voicemail-detection), which detects voicemail at the system level. The voicemail tool puts detection and response entirely in the assistant's hands.
32+
</Note>
33+
34+
## Configuration
35+
36+
Add the voicemail tool to your assistant's tools array:
37+
38+
<CodeBlocks>
39+
```json title="API Configuration"
40+
{
41+
"model": {
42+
"provider": "openai",
43+
"model": "gpt-4o",
44+
"messages": [
45+
{
46+
"type": "system",
47+
"content": "You are a sales representative for Acme Corp. If at any point you determine you're speaking to a voicemail system (greeting mentions 'unavailable', 'leave a message', 'voicemail', etc.), immediately use the leave_voicemail tool."
48+
}
49+
],
50+
"tools": [
51+
{
52+
"type": "voicemail",
53+
"function": {
54+
"name": "leave_voicemail",
55+
"description": "Leave a voicemail message when you detect you've reached a voicemail system"
56+
},
57+
"messages": [
58+
{
59+
"type": "request-start",
60+
"content": "Hi, this is {{company}}. {{message}}. Please call us back at {{phone}}."
61+
}
62+
]
63+
}
64+
]
65+
}
66+
}
67+
```
68+
```typescript title="TypeScript SDK"
69+
import { VapiClient } from "@vapi-ai/server-sdk";
70+
71+
const vapi = new VapiClient({ token: process.env.VAPI_API_KEY });
72+
73+
const assistant = await vapi.assistants.create({
74+
model: {
75+
provider: "openai",
76+
model: "gpt-4o",
77+
messages: [{
78+
type: "system",
79+
content: `You are a sales representative for Acme Corp.
80+
If at any point you determine you're speaking to a voicemail system
81+
(greeting mentions 'unavailable', 'leave a message', 'voicemail', etc.),
82+
immediately use the leave_voicemail tool.`
83+
}],
84+
tools: [{
85+
type: "voicemail",
86+
function: {
87+
name: "leave_voicemail",
88+
description: "Leave a voicemail message when you detect you've reached a voicemail system"
89+
},
90+
messages: [{
91+
type: "request-start",
92+
content: "Hi, this is {{company}}. {{message}}. Please call us back at {{phone}}."
93+
}]
94+
}]
95+
}
96+
});
97+
```
98+
```python title="Python SDK"
99+
from vapi import Vapi
100+
101+
client = Vapi(token=os.getenv("VAPI_API_KEY"))
102+
103+
assistant = client.assistants.create(
104+
model={
105+
"provider": "openai",
106+
"model": "gpt-4o",
107+
"messages": [{
108+
"type": "system",
109+
"content": """You are a sales representative for Acme Corp.
110+
If at any point you determine you're speaking to a voicemail system
111+
(greeting mentions 'unavailable', 'leave a message', 'voicemail', etc.),
112+
immediately use the leave_voicemail tool."""
113+
}],
114+
"tools": [{
115+
"type": "voicemail",
116+
"function": {
117+
"name": "leave_voicemail",
118+
"description": "Leave a voicemail message when you detect you've reached a voicemail system"
119+
},
120+
"messages": [{
121+
"type": "request-start",
122+
"content": "Hi, this is {{company}}. {{message}}. Please call us back at {{phone}}."
123+
}]
124+
}]
125+
}
126+
)
127+
```
128+
</CodeBlocks>
129+
130+
## Message Configuration
131+
132+
Define the voicemail message in the tool configuration:
133+
134+
```json
135+
{
136+
"messages": [
137+
{
138+
"type": "request-start",
139+
"content": "Hi, this is {{company}}. {{message}}. Please call us back at {{phone}}."
140+
}
141+
]
142+
}
143+
```
144+
145+
<Tip>
146+
Use template variables like `{{company}}`, `{{message}}`, and `{{phone}}` to make your voicemail messages dynamic while keeping them consistent.
147+
</Tip>
148+
149+
## Advanced Examples
150+
151+
### Dynamic voicemail with context
152+
153+
```json
154+
{
155+
"model": {
156+
"provider": "openai",
157+
"model": "gpt-4o",
158+
"messages": [
159+
{
160+
"type": "system",
161+
"content": "You are calling leads about their recent inquiry. If you reach voicemail, use the leave_voicemail tool and mention their specific interest."
162+
}
163+
],
164+
"tools": [
165+
{
166+
"type": "voicemail",
167+
"function": {
168+
"name": "leave_voicemail",
169+
"description": "Leave a personalized voicemail message"
170+
},
171+
"messages": [
172+
{
173+
"type": "request-start",
174+
"content": "Hi {{customer_name}}, this is {{agent_name}} from {{company}} following up on your inquiry about {{product_interest}}. I'd love to discuss how we can help. Please call me back at {{callback_number}} or I'll try you again tomorrow. Thanks!"
175+
}
176+
]
177+
}
178+
]
179+
}
180+
}
181+
```
182+
183+
184+
185+
## Best Practices
186+
187+
### Detection prompting
188+
Be specific about voicemail indicators in your system prompt:
189+
- "unavailable"
190+
- "leave a message"
191+
- "voicemail"
192+
- "at the tone"
193+
- "beep"
194+
195+
### Message structure
196+
Keep voicemail messages:
197+
- **Brief** - Under 30 seconds
198+
- **Clear** - State name, company, and purpose
199+
- **Actionable** - Include callback number or next steps
200+
- **Professional** - Match your brand voice
201+
202+
### Error handling
203+
Consider edge cases:
204+
- Long voicemail greetings
205+
- Voicemail box full scenarios
206+
- Systems requiring keypad input
207+
208+
## Voicemail Tool vs. Automatic Detection
209+
210+
| Feature | Voicemail Tool | [Automatic Detection](/calls/voicemail-detection) |
211+
|---------|----------------|---------------------------------------------------|
212+
| Control | Assistant-driven | System-driven |
213+
| Flexibility | High - custom logic | Medium - predefined behavior |
214+
| Cost | Lower - only when used | Higher - continuous monitoring |
215+
| Setup complexity | Simple - just add tool | Moderate - configure detection |
216+
| Message customization | Full control | Limited to configured message |
217+
| Detection accuracy | Depends on prompt | Provider-specific (Vapi, Google, etc.) |
218+
219+
<Info>
220+
Choose the **voicemail tool** when you need maximum flexibility and cost efficiency. Choose **automatic detection** when you need guaranteed system-level detection without relying on assistant prompting.
221+
</Info>
222+
223+
## Common Use Cases
224+
225+
- **Sales outreach** - Personalized follow-up messages
226+
- **Appointment reminders** - Leave detailed appointment information
227+
- **Customer service** - Callback scheduling with ticket numbers
228+
- **Lead qualification** - Leave targeted messages based on lead data
229+
230+
## Next steps
231+
232+
- Learn about other [default tools](/tools/default-tools)
233+
- Explore [automatic voicemail detection](/calls/voicemail-detection) for system-level handling
234+
- See how to create [custom tools](/tools/custom-tools) for your specific needs
235+

0 commit comments

Comments
 (0)