Troubleshooting

Always start with the call history. A Failed call shows the reason below its status. The call details show the transcript, the response times and what each tool returned.

Publishing and access

Symptom	Cause and fix
The agent shows as Not configured	The flow is missing something it needs to be published, usually the Agent Name or a required connector (Model, STT, TTS).
Real calls do not use my changes	They use the published version. Deploy a new version of the flow and click Update publication.
The Widget button is disabled	The agent is not published.
A transfer to another agent does not work	The destination agent is not published. Publish it.
Your application cannot open a call	Check the API key, that the agent’s identifier is the one shown in Request body, and that the agent is published with Enabled on.

Phone

Symptom	Cause and fix
The call does not arrive	The carrier does not send calls to NappAI’s SIP address, or its IP addresses are not in the inbound trunk’s Provider IPs.
It rings but nobody answers	The number is not in Numbers it answers in international format, for example +34910000000, or the agent is not published for Phone (SIP).
It cannot transfer to a phone or place calls	There is no outbound trunk, or it was not chosen when publishing. Also check the trunk’s Username and Password with your carrier.
The called person sees a different number	Check the outbound trunk’s Numbers it may present, or Caller number in Outbound Call. The carrier only lets you show numbers that are yours.

Conversation

Symptom	Cause and fix
It does not use a tool	The tool’s description does not make clear when to use it. Improve it and say it in the prompt too.
It makes up data	Ask in the prompt to always use the tool and to say it does not know when it finds nothing.
It reads figures or phone numbers badly	Ask in the prompt to say them slowly and in groups.
It answers background voices or the TV	Keep Ignore Other Voices on and try Other Voices: How Strict on strict. See Quality, noise and latency.
It stops talking by itself mid-sentence	A noise that sounds like a voice. Raise Minimum Duration To Interrupt or Speech Sensitivity.
It hears itself	The caller is on speakerphone. Turn on Echo Cancellation or recommend headphones.
It hangs up too early	Check Inactivity Before Hanging Up and Maximum Call Duration. If the agent hangs up, look in the history for the reason it gave and adjust the prompt.
It never hangs up	Hang Up Call is missing from Tools, or the prompt does not say when to hang up.
It uses a tool without the data it needs	Mark as required in the tool the data it needs to work. See Voice Agent.
It repeats a question right after using a tool	Have the tool return the data together with any instruction for the agent, and say in that instruction what to tell the caller.
It reads aloud notes that were meant only for it	In the tool’s result, separate what is for the caller from what is an instruction for the agent, or try another model.
Executions shows tools that were not used	Each time the agent uses a tool, every component connected to the Voice Agent is prepared. The tools actually used are the ones that show a tool input and output.

Performance

Symptom	Cause and fix
It is slow to answer	Look at the times in the call details. If the wait is in the agent’s answer, switch to a faster model or lower its reasoning. See Latency.
The first words take long	Set Supertonic’s Quality to 4 steps — Fast, or use Pocket TTS (Spanish only) or Piper.
The call drops because of a provider error	Credential with no balance, retired model or usage limit. Fix the component, or turn on Fallback Engines so a second engine takes over.