Voice AI Troubleshooting

This guide covers common issues with ScendCore’s Voice AI system, which uses Twilio ConversationRelay for inbound and outbound voice calls. The voice-relay service handles AI conversation logic while Twilio manages all audio processing.

How Voice AI Works

1. A caller dials your Twilio number (or clicks a voice widget).
2. Twilio triggers a TwiML webhook pointing to ScendCore’s inbound voice endpoint.
3. The TwiML connects to the voice-relay service via WebSocket.
4. Twilio sends speech-to-text transcriptions to the voice-relay.
5. The voice-relay generates AI responses and sends text back to Twilio.
6. Twilio converts the text to speech and plays it to the caller.

All audio processing (STT, TTS, barge-in) happens on Twilio’s side. ScendCore only sends and receives text.

Common Issues

Problem: Calls show “Busy” in Twilio call log

Cause: This is almost always Twilio error 64101 (invalid TTS voice). The call fails before reaching the voice-relay.

Solution:

1. Go to Twilio Monitor > Logs > Calls.
2. Click the failed call and check the Errors tab for error code 64101.
3. Update the TTS voice to a supported Neural2 voice.

Safe Neural2 voices:

Important: Chirp HD voices (Google.en-US-Chirp-HD-D, etc.) are NOT available in all Twilio accounts. Stick to Neural2 voices to avoid this error.

Fix via dashboard: Go to the agent’s Configuration tab and select a voice from the Voice dropdown.

Problem: Call connects but no AI response

Cause: The voice-relay service may be down or missing required environment variables.

Solution:

1. Check that the voice-relay service is running (verify in your hosting platform’s dashboard).
2. Review the startup logs — the service logs missing env vars at startup.
3. Required variables: SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY.
4. Important optional variables: ANTHROPIC_API_KEY (for tool calling), OPENAI_API_KEY (for RAG embeddings).

Problem: AI speaks but cannot hear the caller

Cause: WebSocket connection issue between Twilio and the voice-relay.

Solution:

1. Verify the ConversationRelay WebSocket URL in your TwiML is correct.
2. Check that the voice-relay service accepts WebSocket connections on the configured port.
3. Ensure the service URL is publicly accessible (not behind a firewall).

Problem: Call disconnects after a few seconds

Cause: The AI agent may not have a greeting configured, or the LLM is failing to respond.

Solution:

1. Check that the AI agent has a greeting set in its configuration.
2. Verify the LLM API key is valid (check startup logs for warnings).
3. Look for timeout errors in the voice-relay logs.

Problem: Agent cannot book meetings during calls

Cause: Calendar integration may not be configured for the agent, or MCP skills are not loaded.

Solution:

1. Ensure the agent has a booking URL or calendar MCP connection configured.
2. Check that the skill_schedule_meeting feature flag is enabled.
3. Verify MCP connections load successfully at call start (check voice-relay logs for “MCP skills loaded”).

Problem: Transferred calls do not reach human agent

Cause: The transfer webhook URL may be misconfigured.

Solution:

1. Verify DASHBOARD_URL is set in the voice-relay environment.
2. Check that VOICE_RELAY_SECRET matches between the voice-relay and dashboard.
3. Review the transfer webhook logs for errors.

Twilio Error Code Reference

Voice Quality Tips

• The AI disclosure statement is always included in the first utterance for compliance.
• Barge-in is enabled by default — callers can interrupt the AI mid-sentence.
• For inbound calls (TCPA-exempt), no consent recording is needed since the contact initiated the call.

ElevenLabs TTS (Advanced)

ScendCore supports ElevenLabs as an alternative TTS provider for higher-quality voices. To use it:

1. Set the ELEVENLABS_API_KEY environment variable on the voice-relay service.
2. Configure the agent’s elevenlabs_voice_id field.
3. Set VOICE_RELAY_URL for audio serving.

When ElevenLabs is configured, the voice-relay generates audio files and serves them to Twilio via <Play> instead of using Twilio’s built-in TTS.

Diagnostic Checklist

1. Check Twilio Monitor > Logs > Calls for error codes
2. Check voice-relay startup logs for missing env vars
3. Verify the agent has a greeting and valid voice setting
4. Test with a known-good Neural2 voice (Google.en-US-Neural2-F)
5. Confirm WebSocket connectivity to the voice-relay service