Account

Troubleshooting

The most common issues, the cause, and the fix. Start here before opening a support ticket - most of these resolve in under a minute.

Agent doesn't say anything when the call connects

Cause: The system prompt is empty, the voice provider key isn't valid, or the LLM is returning an empty completion (rare).

Fix:

Open the agent → confirm the system prompt has a clear opening greeting (e.g. “Greet the caller and ask how you can help.”).
If you BYOK'd the voice provider, test the key under Settings → Providers. Floo's pooled keys are always green-lit.
Run a browser test - if it works there but not on the phone, the issue is in the telephony layer (check Twilio webhook delivery).

Calls drop after 5 seconds

Cause: Almost always insufficient wallet balance. Floo terminates calls when balance falls below $0.20 to avoid negative balance.

Fix:

Top up under Settings → Billing. If your balance is healthy, open the call detail page - the termination_reason field tells you exactly what happened (provider 5xx, RTC disconnect, user-hangup, etc.).

Voice sounds robotic or unnatural

Cause: You're on the Starter tier (Cartesia Sonic-3) and your prompt has overly formal language that the model reads literally.

Fix:

Upgrade to Pro or Business (ElevenLabs voices) - biggest single quality improvement.
Rewrite the prompt in conversational English: contractions (“I'll” not “I will”), short sentences, no jargon.
Add SSML hints sparingly - pauses with <break time="300ms"/> help on long sentences.

Knowledge base search returns nothing relevant

Cause: Either the KB hasn't finished embedding yet, the document is image-heavy (no OCR), or the chunks are too noisy because the source lacks headings.

Fix:

Check the KB source status - it should say ready. If it's still processing, wait - large files can take a few minutes.
Open the call detail → Knowledge retrievals tab. If you see the right chunk being retrieved but the agent doesn't use it, the system prompt isn't instructing the agent to rely on KB. Add: “Always check the knowledge base before answering factual questions.”
Re-upload with cleaner formatting - add Markdown headings before each topic.

Twilio webhook timing out

Cause: Twilio expects a response within 15s. If your agent's first response generation exceeds that (cold start on a custom LLM, slow KB on a huge corpus), Twilio drops the call.

Fix:

Use a fast LLM like OpenAI GPT-4o mini (Starter or Pro tier) for sub-second time to first token.
If you BYOK'd a custom LLM, make sure it's warm (keep-alive ping) or switch back to our pooled providers.
Trim oversized KBs - if you have >1,000 chunks, search adds latency. Split into multiple smaller KBs scoped per use case.

API returning 401 Unauthorized

Cause: Your API key is wrong, revoked, or you're using a key from a different workspace.

Fix:

Confirm the key is active under Settings → API keys (revoked keys disappear, expired keys show a red badge).
Make sure you're sending it as Authorization: Bearer YOUR_KEY - a common mistake is X-API-Key(we don't accept that header).
If you have multiple workspaces, double-check you minted the key from the workspace whose data you're trying to access.

Insufficient balance error before the call even starts

Cause: Floo estimates the cost of a 1-minute call before placing it, and rejects if your wallet can't cover it.

Fix:

Top up under Settings → Billing. Minimum $10. Once auto-recharge ships you can avoid these interruptions entirely.

Agent keeps interrupting the caller

Cause: The interruption sensitivity is too aggressive (default 0.7). The agent thinks the caller paused when they were still mid-sentence.

Fix:

Open the agent → Advanced → lower interruption sensitivity to 0.4 or 0.5.
If the caller is in a noisy environment, also raise the noise gate threshold. Floo gates background hum below ~30dB by default.

Numbers in the agent's response are read wrong (e.g. phone numbers)

Cause: Most TTS engines read “123-456” as “one hundred twenty three” instead of digit-by-digit.

Fix:

Add an explicit instruction to the system prompt: “When reading phone numbers, dates, or amounts, speak each digit separately (e.g. one-two-three, not one hundred twenty three).” ElevenLabs voices follow this reliably; Cartesia is hit-or-miss.

Webhook isn't firing for completed calls

Cause: Either your endpoint is returning a non-2xx, your URL is HTTPS-only and you registered an HTTP URL, or the webhook is paused after 10 consecutive failures.

Fix:

Check Settings → Webhooks → click your endpoint → see the delivery log. Failed deliveries show response status + body.
Floo retries with exponential backoff up to 24 hours. Endpoints failing 10 deliveries in a row are auto-paused - you have to manually re-enable.
We require HTTPS in production. Use ngrok or similar for local dev.

Didn't find your issue?

Send us your agent ID + the call ID (you'll find it in the URL on the call detail page) and we'll dig into the logs.

Contact support