Calls
Troubleshoot Errors
A practical diagnosis path for the failures that actually happen in production: calls that never connect, agents that go silent, tools that time out, and transfers that drop.
Start here
- 1
Read the end reason
Open the call in Data → Call Logs. The end reason narrows the cause to one of four classes: caller, config, tool, or pipeline.
- 2
Open the timeline
The timeline shows every turn, tool call, latency spike, and control action with timestamps. Failures are marked in the stream.
- 3
Reproduce in Testing Lab
Replay the same scenario against the current agent version. If it passes there, the problem is data or telephony, not the prompt.
- 4
Check Observability
Monitoring shows whether the failure is isolated to one call or affecting the whole workspace.
Calls never connect
- invalid-number — The list was not normalized. Validate to E.164 before upload — CSV Upload flags bad rows, but API calls do not.
- blocked — Your caller ID is being spam-flagged. Register the number for branded caller ID and rotate across a pool.
- carrier-error on every attempt — The number is not fully provisioned or the SIP trunk credentials expired. Re-verify under Settings → Phone Numbers.
- 403 from the API — The key is scoped read-only or belongs to another workspace. Create a key with calls:write.
The agent connects but says nothing
Almost always a first-turn problem. Confirm the agent has a greeting, that the assigned voice is still valid, and that a custom TTS provider (if configured) is returning audio. A pipeline-error-tts on the first turn means credentials, not prompt.
The agent talks over the caller
- Interruption threshold too low — Raise it in Conversation Behavior so background noise does not register as speech.
- Speaker echo — Callers on speakerphone can trigger self-interruption. Enable echo suppression.
- Long fillers — Shorten the greeting; a 20-word opener invites the caller to cut in.
Tool calls fail
| Symptom | Cause | Fix |
|---|---|---|
| tool-error after ~10s | Endpoint slower than the tool timeout. | Make the endpoint async or raise the timeout to 20s. |
| Agent invents a result | Tool description too vague; the model guessed. | Tighten the description and mark parameters required. |
| 401 from your endpoint | Auth header not set on the tool. | Add the key under Settings → Integrations, not in the prompt. |
| Tool never fires | No trigger phrasing in the prompt. | Explicitly instruct when to call it; test in Testing Lab. |
Transfers drop the caller
Cold transfers fail silently when the destination is unreachable. Always set a fallback (voicemail or another number) and prefer warm transfers for anything revenue-critical.
Latency feels bad
- Target — Under 800ms end-of-speech to first audio feels natural. Above 1.5s, callers start talking again.
- Biggest lever — Model choice. A smaller model on the fast tier usually beats prompt micro-optimization.
- Second lever — Knowledge base size. Trim stale documents; retrieval scales with corpus.
- Third lever — Synchronous tools. Anything over 500ms should be fired-and-forgotten where possible.