Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ravan.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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 Thunder Emotion Lite to Thunder Emotion 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 info@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 Thunder Emotion, 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 info@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.