​
Troubleshooting

A quick reference for diagnosing and fixing the most common issues with Agni voice agents.

​
Call Issues

Check these in order:
  1. Phone number active? — Go to Phone Numbers in the dashboard. Ensure your number is active and not released.
  2. Agent status — Verify the agent is set to ACTIVE (not paused or draft).
  3. Inbound dispatch rule — For inbound calls, ensure a dispatch rule routes your phone number to the correct agent.
  4. Twilio balance — If using BYOT, check your Twilio account has sufficient balance.
  5. Number region — International calls may be blocked by default. Check Twilio geo-permissions.
Common causes:
  • Model too heavy — Switch from gpt-4o to gpt-4o-mini for faster first response
  • Long system prompt — Trim your prompt to under 500 words
  • Welcome message missing — Set a begin_message so the agent speaks immediately on connection
  • Start speaker set to “user” — If you want the agent to speak first, set start_speaker to "agent"
For web calls:
  • Allow microphone permission in your browser
  • Check you’re using a supported browser (Chrome, Edge, Firefox)
  • Disable browser extensions that block WebRTC
For phone calls:
  • Test with a different phone to rule out device issues
  • Check if the call connects but only one party can hear — this usually indicates a network/NAT issue on the telephony side
  • Max call duration — Check max_call_duration_ms in agent settings. Default may be too short.
  • End on silence — If end_call_after_silence is enabled, the agent hangs up during pauses. Increase the silence threshold or disable it.
  • Twilio limits — BYOT accounts may have call duration limits. Check your Twilio console.
  • Network issues — Intermittent connectivity on the caller’s side causes drops.
  • Prompt too vague — Add specific instructions and examples. See the Prompt Engineering Guide.
  • Temperature too high — Lower the temperature (0.3-0.5) for more deterministic responses.
  • Knowledge base stale — Refresh your knowledge base if answers reference outdated information.
  • No guardrails — Add explicit “do NOT” rules for topics the agent should avoid.
  • Transfer number format — Use E.164 format: +14155551234
  • SIP address — For SIP transfers, verify the SIP URI is correct and reachable
  • Tool configured? — Ensure the Call Transfer tool is attached to the agent in the Functions tab
  • Trigger description — The tool’s trigger description must clearly define when to transfer

​
Integration Issues

GoHighLevel:
  • Re-authorize the OAuth connection in Settings → Integrations
  • Verify the GHL calendar ID is correct
  • Check that the GHL account has the Calendars permission enabled
Cal.com:
  • Reconnect via Settings → Integrations → Cal.com
  • Ensure the event type exists and is active in your Cal.com dashboard
  • Check timezone settings match between Agni and Cal.com
  • URL accessible? — Test your endpoint with curl -X POST https://your-url.com/webhook
  • HTTPS required — Agni only sends webhooks over HTTPS
  • Check logs — Look at your agent’s webhook delivery logs in the dashboard
  • Return 200 — Your server must return HTTP 200 within 30 seconds or it’s marked as failed
  • See the Webhooks Guide for setup details.
  • Check API key — Copy the key fresh from Settings → API Keys
  • Header name — Use X-Api-Key (not Authorization: Bearer)
  • Key active? — Regenerate the key if it may have been revoked
  • No extra spaces — Ensure no trailing whitespace in the key
You’ve hit the rate limit. Solutions:
  • Add retry logic with exponential backoff
  • Reduce request frequency
  • Use webhooks instead of polling for status updates
  • Contact support@ravan.ai for higher limits on enterprise plans

​
Voice Quality

  • Try a different voice — Some voices sound more natural. Test several in the voice picker.
  • Lower temperature — Very low temperatures (0.1) can make speech sound mechanical. Try 0.5.
  • Shorten responses — Add “Keep your responses to 1-2 sentences” to your prompt.
  • Add personality — Prompts like “speak casually and warmly” improve naturalness.
  • Responsiveness — Increase the responsiveness setting to make the agent more patient before responding
  • Turn-taking — Enable backchanneling so the agent uses filler words (“Mhm”, “I see”) while listening
  • Prompt instruction — Add: “Wait for the caller to finish speaking before responding.”
  • Ambient sound volume — If using background sounds, lower ambient_sound_volume to 0.1-0.3
  • Caller side — Background noise from the caller is harder to control. The agent’s speech recognition handles moderate noise well.

​
Quick Fixes Checklist

SymptomQuick Fix
Call doesn’t connectCheck phone number is active + dispatch rule exists
Agent doesn’t speakSet begin_message and start_speaker: "agent"
Slow first responseSwitch to gpt-4o-mini, shorten prompt
Wrong answersLower temperature, add guardrails to prompt
Transfer failsCheck E.164 format, verify tool is attached
Webhook not receivedVerify HTTPS URL, check it returns 200
401 API errorUse X-Api-Key header with valid key
Calendar not syncingRe-authorize OAuth in Settings

​
Getting Help

If you’ve gone through this guide and the issue persists:

Email Support

Reach out to support@ravan.ai with your agent ID and a description of the issue.

API Reference

Check the API docs for endpoint-specific error codes and parameters.