Voice System Troubleshooting

Common issues and solutions for the Voice system.

Call Not Answered

Symptoms

• Call rings but is not answered
• Call goes to voicemail
• No assistant response

Solutions

1. Verify Phone Number Configuration

   • Check phone number has Voice capability enabled
   • Verify number is connected to correct Telnyx Connection
   • Check number is linked to Telnyx Conversational AI profile

2. Check Telnyx Configuration

   • Navigate to Settings → Voice Provider
   • Verify Telnyx API key is configured correctly
   • Check Telnyx Connection ID is set

3. Verify Default Voice Assistant

   • Navigate to Assistants page
   • Verify default voice assistant is configured
   • Check assistant is active and not disabled

4. Check Webhook Configuration

   • Verify webhook URL is correct in Telnyx Mission Control
   • Check webhook events are being received
   • Review webhook logs for errors
   • Verify webhook authentication/signing secret

5. Review System Logs

   • Check system logs for webhook errors
   • Look for authentication failures
   • Verify tenant resolution is working

---

No Transcripts Appearing

Symptoms

• Call completed but no transcript in conversation
• Messages not showing in conversation detail
• Partial transcripts only

Solutions

1. Verify Webhook Events

   • Check webhook events are being received
   • Verify ai.assistant.transcript events are received
   • Review webhook logs for transcript events

2. Check Assistant Configuration

   • Verify assistant is configured correctly
   • Check system prompt and settings
   • Ensure assistant is active

3. Review Message Persistence

   • Check conversation exists in database
   • Verify messages are being saved
   • Check for database errors

4. Check Transcript Processing

   • Verify transcript events are being processed
   • Check for errors in transcript handler
   • Review system logs for processing errors

---

Recording Not Available

Symptoms

• Call completed but no recording available
• Recording shows as "unavailable"
• Recording URL returns 404

Solutions

1. Verify Recording is Enabled

   • Navigate to Settings → Voice Settings
   • Check "Call Recording" is enabled
   • Verify recording settings are configured

2. Check Recording Processing

   • Recordings may take a few minutes to process
   • Wait 5-10 minutes after call ends
   • Refresh conversation detail page

3. Verify Recording Webhook

   • Check call.recording.saved webhook events are received
   • Review webhook logs for recording events
   • Verify recording metadata is saved

4. Check Telnyx Recording Settings

   • Verify recording is enabled in Telnyx Connection
   • Check recording settings in Telnyx Mission Control
   • Verify recording format and storage

5. Review Recording Metadata

   • Check conversation metadata for recording info
   • Verify recording URLs are valid
   • Check recording ID is present

---

Assistant Not Responding

Symptoms

• Call answered but assistant doesn't respond
• Silence after greeting
• Assistant responses delayed or missing

Solutions

1. Check Assistant Configuration

   • Verify default voice assistant is configured
   • Check assistant system prompt
   • Verify assistant is active

2. Review Conversational AI Status

   • For Telnyx: Check Conversational AI is started
   • Verify profile is synced correctly
   • Check for AI service errors

3. Check Tool Execution

   • Verify tools are configured correctly
   • Check for tool execution errors
   • Review tool call logs

4. Review System Logs

   • Check for AI service errors
   • Look for timeout errors
   • Verify API connectivity

5. Test Assistant in Other Channels

   • Test assistant in chat or SMS
   • Verify assistant works in other channels
   • Compare behavior across channels

---

Poor Audio Quality

Symptoms

• Audio is choppy or distorted
• Delayed responses
• Poor transcription accuracy

Solutions

1. Check Network Connection

   • Verify stable internet connection
   • Check for network latency issues
   • Test from different network

2. Review Provider Settings

   • Check audio codec settings
   • Verify audio quality settings
   • Review provider documentation

3. Check Call Quality Metrics

   • Review call quality metrics in analytics
   • Check for consistent quality issues
   • Compare with other calls

4. Contact Telnyx Support

   • Contact Telnyx support for quality issues
   • Provide call details and timestamps
   • Reference: Telnyx Support

---

Webhook Errors

Symptoms

• Webhook events not received
• Webhook signature verification failures
• Webhook processing errors

Solutions

1. Verify Webhook URL

   • Check webhook URL is correct
   • Verify URL is accessible
   • Test webhook endpoint manually

2. Check Webhook Secret

   • Verify webhook secret is configured correctly
   • Check secret matches in provider dashboard
   • Update secret if needed

3. Review Signature Verification

   • Check signature verification is working
   • Verify timestamp is within acceptable range
   • Review signature verification logs

4. Check Webhook Rate Limits

   • Verify webhook rate limits are not exceeded
   • Check for rate limit errors
   • Review provider rate limit settings

---

Analytics Not Updating

Symptoms

• Analytics show outdated data
• Metrics not reflecting recent calls
• Timeline data missing

Solutions

1. Check Cache

   • Analytics use caching (60 seconds for overview, 5 minutes for timeline)
   • Wait for cache to expire
   • Clear cache if needed

2. Verify Data Collection

   • Check conversations are being created
   • Verify metadata is being saved
   • Review data collection logs

3. Check Date Filters

   • Verify date filters are correct
   • Check timezone settings
   • Review date range queries

4. Review Analytics Queries

   • Check for query errors
   • Verify database connectivity
   • Review analytics processing logs

---

Integration Issues

CRM Sync Not Working

1. Verify CRM Integration

   • Check CRM integration is configured
   • Verify API keys are correct
   • Test CRM connection

2. Check Sync Settings

   • Verify "Sync Voice Calls" is enabled
   • Check "Qualified Only" setting if applicable
   • Review sync filters

3. Review Sync Logs

   • Check for sync errors
   • Verify contact matching
   • Review sync processing

Qualification Not Working

1. Check Qualification Settings

   • Verify qualification criteria are configured
   • Check voice calls are included
   • Review qualification rules

2. Verify Call Data

   • Check call duration meets threshold
   • Verify keywords are present
   • Review qualification analysis

---

Getting Help

If you continue to experience issues:

1. Check System Logs

   • Review application logs
   • Check webhook logs
   • Look for error patterns

2. Contact Support

   • Provide detailed error information
   • Include call IDs and timestamps
   • Share relevant logs

3. Review Documentation

   • Overview - Voice system overview
   • Setup Guide - Setup instructions
   • Configuration - Configuration options
   • API Reference - API documentation

---

Common Error Messages

"Missing tenant context"

• Cause: Authentication issue
• Solution: Verify authentication token is valid

"Conversation not found"

• Cause: Conversation ID is invalid or doesn't exist
• Solution: Verify conversation ID is correct

"No default voice assistant configured"

• Cause: Default voice assistant not set
• Solution: Configure default voice assistant in Assistants

"Webhook signature invalid"

• Cause: Webhook secret mismatch
• Solution: Verify webhook secret matches provider configuration

"Recording not available"

• Cause: Recording not enabled or not processed yet
• Solution: Enable recording and wait for processing

---

Next Steps

• Overview - Voice system overview
• Setup Guide - Initial setup
• Configuration - Advanced settings
• API Reference - API documentation