Skip to content

Commit 6cea766

Browse files
authored
Add videos to guide for debugging voice agents (#476)
* feat(debugging): add videos, update provider status links and wording * fix(introduction): simplify structure, address layout issues, add link icons * fix(debugging): formatting issues * chore(debugging): add extra bullet point on top card group * fix(debugging): cta for assistants and workflows * chore(debugging): add link icons
1 parent 77e7af7 commit 6cea766

File tree

7 files changed

+105
-48
lines changed

7 files changed

+105
-48
lines changed

fern/debugging.mdx

Lines changed: 73 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,20 @@ slug: debugging
88

99
Voice agents involve multiple AI systems working together—speech recognition, language models, and voice synthesis. When something goes wrong, systematic debugging helps you quickly identify and fix the root cause.
1010

11-
**Common debugging scenarios:**
12-
- Agent doesn't understand user input correctly
13-
- Responses are inappropriate or inconsistent
14-
- Call quality issues or audio problems
15-
- Tool integrations failing or returning errors
16-
- Workflow logic not executing as expected
11+
**Most common issues fall into these categories:**
12+
13+
<CardGroup cols={2}>
14+
<Card title="Speech & Understanding" icon="microphone">
15+
* Agent doesn't understand user input correctly
16+
* Responses are inappropriate or inconsistent
17+
* Agent sounds robotic or unnatural
18+
</Card>
19+
<Card title="Technical & Integration" icon="gear">
20+
* Call quality issues or audio problems
21+
* Tool integrations failing or returning errors
22+
* Workflow logic not executing as expected
23+
</Card>
24+
</CardGroup>
1725

1826
## Quick diagnostics
1927

@@ -23,31 +31,59 @@ Start with these immediate checks before diving deeper:
2331
<Step title="Test in dashboard">
2432
Test your voice agent directly in the [dashboard](https://dashboard.vapi.ai/):
2533

26-
- **Assistants**: `Dashboard > Assistants > [Select Assistant] > Talk to Assistant`
27-
- **Workflows**: `Dashboard > Workflows > [Select Workflow] > Call`
34+
<CardGroup cols={2}>
35+
<Card title="Assistants" icon="robot">
36+
Click "Talk to Assistant" to test
37+
</Card>
38+
<Card title="Workflows" icon="diagram-project">
39+
Click "Call" to test workflow
40+
</Card>
41+
</CardGroup>
42+
43+
**Benefits:**
2844
- Eliminates phone network variables
29-
- Provides real-time transcript view
45+
- Provides real-time transcript view
3046
- Shows tool execution results immediately
3147
</Step>
3248
<Step title="Check logs">
3349
Navigate to the `Observe` section in your [dashboard](https://dashboard.vapi.ai/) sidebar:
3450

35-
- **Call Logs**: Review call transcripts, durations, and error messages
36-
- **API Logs**: Check API requests and responses for integration issues
37-
- **Webhook Logs**: Verify webhook deliveries and server responses
51+
<CardGroup cols={3}>
52+
<Card title="Call Logs" icon="phone">
53+
Review call transcripts, durations, and error messages
54+
</Card>
55+
<Card title="API Logs" icon="code">
56+
Check API requests and responses for integration issues
57+
</Card>
58+
<Card title="Webhook Logs" icon="webhook">
59+
Verify webhook deliveries and server responses
60+
</Card>
61+
</CardGroup>
3862
</Step>
3963
<Step title="Test individual components">
4064
Use [dashboard](https://dashboard.vapi.ai/) testing features:
4165

42-
- **Voice Test Suites**: `Test > Voice Test Suites` (assistants only)
43-
- **Tool Testing**: `Tools > [Select Tool] > Test` with sample payloads
66+
<CardGroup cols={2}>
67+
<Card title="Voice Test Suites" icon="vial">
68+
Automated testing for assistants
69+
</Card>
70+
<Card title="Tool Testing" icon="wrench">
71+
Test tools with sample data
72+
</Card>
73+
</CardGroup>
4474
</Step>
4575
<Step title="Verify provider status">
4676
Check if AI service providers are experiencing issues:
4777

48-
- Visit [Vapi Status Page](https://status.vapi.ai/) for real-time provider status
49-
- Review speech-to-text, language model, and voice synthesis availability
50-
- Check for ongoing maintenance or outages
78+
**Core Services:**
79+
- Visit [Vapi Status Page](https://status.vapi.ai/) for Vapi service status
80+
81+
**Provider Status Pages:**
82+
- [OpenAI Status](https://status.openai.com/) for OpenAI language models
83+
- [Anthropic Status](https://status.anthropic.com/) for Anthropic language models
84+
- [ElevenLabs Status](https://status.elevenlabs.io/) for ElevenLabs voice synthesis
85+
- [Deepgram Status](https://status.deepgram.com/) for Deepgram speech-to-text
86+
- And other providers' status pages as needed
5187
</Step>
5288
</Steps>
5389

@@ -64,6 +100,8 @@ Navigate to `Observe > Call Logs` to:
64100
- See tool execution results and errors
65101
- Analyze conversation flow in workflows
66102

103+
<video autoPlay loop muted src="./static/videos/debugging/call-logs.mp4" type="video/mp4" style={{ aspectRatio: '16 / 9', width: '100%' }} />
104+
67105
### API Logs
68106

69107
Navigate to `Observe > API Logs` to:
@@ -72,6 +110,8 @@ Navigate to `Observe > API Logs` to:
72110
- Verify request payloads and response codes
73111
- Debug integration issues with external services
74112

113+
<video autoPlay loop muted src="./static/videos/debugging/api-logs.mp4" type="video/mp4" style={{ aspectRatio: '16 / 9', width: '100%' }} />
114+
75115
### Webhook Logs
76116

77117
Navigate to `Observe > Webhook Logs` to:
@@ -80,6 +120,8 @@ Navigate to `Observe > Webhook Logs` to:
80120
- Debug webhook authentication issues
81121
- Monitor event delivery failures
82122

123+
<video autoPlay loop muted src="./static/videos/debugging/webhook-logs.mp4" type="video/mp4" style={{ aspectRatio: '16 / 9', width: '100%' }} />
124+
83125
### Voice Test Suites
84126

85127
Navigate to `Test > Voice Test Suites` to:
@@ -88,6 +130,8 @@ Navigate to `Test > Voice Test Suites` to:
88130
- Verify assistant behavior across different inputs
89131
- Monitor performance over time
90132

133+
<video autoPlay loop muted src="./static/videos/debugging/voice-test-suites.mp4" type="video/mp4" style={{ aspectRatio: '16 / 9', width: '100%' }} />
134+
91135
### Tool Testing
92136

93137
For any tool in your `Tools` section:
@@ -96,6 +140,8 @@ For any tool in your `Tools` section:
96140
- Verify tool responses and error handling
97141
- Debug parameter extraction and API calls
98142

143+
<video autoPlay loop muted src="./static/videos/debugging/tool-testing.mp4" type="video/mp4" style={{ aspectRatio: '16 / 9', width: '100%' }} />
144+
99145
## Speech and language issues
100146

101147
| Problem | Symptoms | Solution |
@@ -138,7 +184,7 @@ For any tool in your `Tools` section:
138184

139185
| Error Pattern | Likely Cause | Quick Fix |
140186
|---------------|--------------|-----------|
141-
| **"I didn't understand"** | Speech recognition issue | Check transcriber model, add custom keyterms |
187+
| **Agent misinterpreting speech** | Speech recognition issue | Check transcriber model, add custom keyterms |
142188
| **Irrelevant responses** | Poor prompt engineering | Be more specific in system prompt |
143189
| **Call drops immediately** | Configuration error | Check all required fields in assistant/workflow settings |
144190
| **Tool errors** | API integration issue | Test tools individually, verify endpoint URLs |
@@ -153,6 +199,9 @@ When you're stuck:
153199
icon="user-group"
154200
href="https://discord.com/invite/pUFNcf2WmH"
155201
>
202+
<div className='absolute top-4 right-4'>
203+
<Icon icon="arrow-up-right-from-square" />
204+
</div>
156205
Join the Vapi Discord for real-time help from the community and team
157206
</Card>
158207

@@ -161,6 +210,9 @@ When you're stuck:
161210
icon="book"
162211
href="/api-reference"
163212
>
213+
<div className='absolute top-4 right-4'>
214+
<Icon icon="arrow-up-right-from-square" />
215+
</div>
164216
Check the API reference for detailed configuration options
165217
</Card>
166218

@@ -169,6 +221,9 @@ When you're stuck:
169221
icon="fa-light fa-heartbeat"
170222
href="https://status.vapi.ai/"
171223
>
224+
<div className='absolute top-4 right-4'>
225+
<Icon icon="arrow-up-right-from-square" />
226+
</div>
172227
Check real-time status of Vapi services and AI providers
173228
</Card>
174229

fern/quickstart/introduction.mdx

Lines changed: 32 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -43,29 +43,31 @@ Vapi offers two main primitives for building voice agents, each designed for dif
4343
iconType="solid"
4444
href="/assistants/dynamic-variables"
4545
>
46-
**Best for:** Quick kickstart and straightforward conversations
47-
46+
<div className='absolute top-4 right-4'>
47+
<Icon icon="arrow-up-right-from-square" />
48+
</div>
49+
**Best for:** Quick kickstart for simple conversations
50+
<br />
4851
Assistants use a single system prompt to control behavior. Perfect for:
4952
- Customer support chatbots
5053
- Simple question-answering agents
5154
- Getting started quickly with minimal setup
52-
53-
*Control everything from one place with natural language instructions.*
5455
</Card>
5556
<Card
5657
title="Workflows"
5758
icon="diagram-project"
5859
iconType="solid"
5960
href="/workflows/quickstart"
6061
>
62+
<div className='absolute top-4 right-4'>
63+
<Icon icon="arrow-up-right-from-square" />
64+
</div>
6165
**Best for:** Complex logic and multi-step processes
62-
66+
<br />
6367
Workflows use visual decision trees and conditional logic. Perfect for:
6468
- Appointment scheduling with availability checks
6569
- Lead qualification with branching questions
66-
- Complex customer service flows with escalation paths
67-
68-
*Build sophisticated branching logic without code.*
70+
- Complex customer service flows with escalation
6971
</Card>
7072
</CardGroup>
7173

@@ -86,8 +88,10 @@ Vapi offers two main primitives for building voice agents, each designed for dif
8688
iconType="solid"
8789
href="/quickstart/phone"
8890
>
89-
**Start here if you want to:**
90-
- Create a voice agent that can make and receive phone calls
91+
<div className='absolute top-4 right-4'>
92+
<Icon icon="arrow-up-right-from-square" />
93+
</div>
94+
- Create a voice agent for inbound/outbound calls
9195
- Build customer support or sales automation
9296
- Get started with no coding required
9397

@@ -99,7 +103,9 @@ Vapi offers two main primitives for building voice agents, each designed for dif
99103
iconType="solid"
100104
href="/quickstart/web"
101105
>
102-
**Start here if you want to:**
106+
<div className='absolute top-4 right-4'>
107+
<Icon icon="arrow-up-right-from-square" />
108+
</div>
103109
- Add voice capabilities to your web application
104110
- Integrate voice chat into your existing product
105111
- Build with code and SDKs
@@ -117,35 +123,38 @@ Vapi offers two main primitives for building voice agents, each designed for dif
117123
iconType="solid"
118124
href="/examples/inbound-support"
119125
>
126+
<div className='absolute top-4 right-4'>
127+
<Icon icon="arrow-up-right-from-square" />
128+
</div>
120129
<div class="vapi-badge vapi-badge-assistant">Built with Assistants</div>
121130

122131
Automate inbound support calls with agents that can access your knowledge base and escalate to humans when needed.
123-
124-
*View example →*
125132
</Card>
126133
<Card
127134
title="Sales & Lead Qualification"
128135
icon="phone-office"
129136
iconType="solid"
130137
href="/workflows/examples/lead-qualification"
131138
>
139+
<div className='absolute top-4 right-4'>
140+
<Icon icon="arrow-up-right-from-square" />
141+
</div>
132142
<div class="vapi-badge vapi-badge-workflow">Built with Workflows</div>
133143

134144
Make outbound sales calls, qualify leads, and schedule appointments with sophisticated branching logic.
135-
136-
*View example →*
137145
</Card>
138146
<Card
139147
title="Appointment Scheduling"
140148
icon="calendar-check"
141149
iconType="solid"
142150
href="/workflows/examples/appointment-scheduling"
143151
>
152+
<div className='absolute top-4 right-4'>
153+
<Icon icon="arrow-up-right-from-square" />
154+
</div>
144155
<div class="vapi-badge vapi-badge-workflow">Built with Workflows</div>
145156

146157
Handle booking requests, check availability, and confirm appointments with conditional routing.
147-
148-
*View example →*
149158
</Card>
150159
</CardGroup>
151160

@@ -156,6 +165,9 @@ Vapi offers two main primitives for building voice agents, each designed for dif
156165
iconType="solid"
157166
href="/workflows/examples/clinic-triage-scheduling"
158167
>
168+
<div className='absolute top-4 right-4'>
169+
<Icon icon="arrow-up-right-from-square" />
170+
</div>
159171
<div class="vapi-badge vapi-badge-workflow">Built with Workflows</div>
160172

161173
Emergency routing and appointment scheduling for healthcare.
@@ -166,21 +178,11 @@ Vapi offers two main primitives for building voice agents, each designed for dif
166178
iconType="solid"
167179
href="/workflows/examples/ecommerce-order-management"
168180
>
181+
<div className='absolute top-4 right-4'>
182+
<Icon icon="arrow-up-right-from-square" />
183+
</div>
169184
<div class="vapi-badge vapi-badge-workflow">Built with Workflows</div>
170185

171186
Order tracking, returns, and customer support workflows.
172187
</Card>
173188
</CardGroup>
174-
175-
## Ready to get started?
176-
177-
Most users start with **phone calls** since it's the easiest way to see Vapi in action. You can create and test a working voice agent in under 5 minutes without writing any code.
178-
179-
<Card
180-
title="Start with Phone Calls →"
181-
icon="phone"
182-
iconType="solid"
183-
href="/quickstart/phone"
184-
>
185-
Create your first voice agent and make your first call
186-
</Card>
1.89 MB
Binary file not shown.
2.21 MB
Binary file not shown.
2.45 MB
Binary file not shown.
Binary file not shown.
2.1 MB
Binary file not shown.

0 commit comments

Comments
 (0)