Common issues

Diagnosis steps:

1. Open the conversation in Conversations and enable Topic citations in the Diagnosis toggle group on the Transcription tab.
2. Check which topic was retrieved – is it the right one?
3. If the wrong topic was retrieved, the sample questions or topic names may be too similar between topics. Make them more distinct.
4. If the right topic was retrieved but the answer is wrong, update the Content field.

Common causes:

• Two topics with overlapping sample questions – the retriever picks the wrong one
• Topic name is too vague (e.g., info or general) and matches too broadly
• Content is outdated or incomplete

Diagnosis steps:

1. Check that the topic has been published and promoted to the environment you are testing in.
2. Verify the topic has sample questions – without them, retrieval accuracy drops significantly.
3. Test different phrasings. If only very specific wording triggers the topic, add more varied sample questions.

Common causes:

• Topic exists in Sandbox but hasn’t been promoted to Live
• Sample questions are too few or too narrow
• Topic name is not semantically related to the user’s query

When a topic instructs the agent to both say something and call a function in the same turn, the agent may do one but not the other. This is a common anti-pattern.

Fix: Structure actions so the agent only has one task per turn. If you need to say something and then call a function, split the instruction across turns – let the agent deliver the answer first, then handle the action in a follow-up.

The change may be pulling from cached audio. Go to Voice > Audio library, find the specific audio clip, update the speed setting, and regenerate the audio.

Use the Pronunciation section in Voice > Advanced settings > Speech. You can provide IPA notation, SSML overrides, or regex-based corrections. See Audio Management for details.

The disclaimer uses a separate voice configuration. Check Voice > Settings – the Disclaimer section has its own voice selection and tuning, independent of the main agent voice.

You need to publish your changes and then promote them through your environments (Sandbox → Pre-release → Live). Changes in Draft or Sandbox are not automatically applied to Live.

See Environments for the full promotion flow.

1. Wait a few minutes – promotion can take a short time to propagate.
2. Check that you promoted the correct version by comparing version numbers in the Environments page.
3. If using a phone number to test, confirm the number is assigned to the correct environment.

If there are no knowledge topics published to the Live environment, the agent has nothing to say after the disclaimer and will end the call. Ensure at least one topic is published and promoted before going live.

1. Check that the function is referenced in a topic’s Actions field or a step’s function list using @function_name.
2. Verify the function description is clear – the LLM uses it to decide when to call the function.
3. Check for typos in the function name reference.
4. Use conv.log statements to confirm whether the function is being reached at all.

Check the goto_step calls in your flow functions. A common bug is using multiple if statements instead of if/elif/else, which causes later transitions to overwrite earlier ones. See Flow fundamentals for the correct pattern.

1. Add conv.log statements to trace execution.
2. Check the function’s parameters match what the LLM is passing.
3. If calling an external API, verify secrets are configured for the correct environment.
4. Review the conversation in Conversations with the Tool calls diagnosis toggle enabled.

See Function maintenance for detailed debugging steps.

1. Verify the forwarding number is correct and includes the country code.
2. Check that call forwarding is enabled with your telephone provider.
3. Ensure the transfer number is not part of the same ring group as the mainline number, which can create a loop.

1. Check that the transfer number includes the country code (starts with +).
2. For SIP transfers, verify the URI and any custom headers.
3. Test in Sandbox first before promoting to Live.
4. If using Twilio, confirm the fallback number is configured correctly.

See Routing and handoffs for step-by-step guidance.

Some telephone providers mask the caller number during forwarding, replacing it with the restaurant or business number. Contact your telephone provider and ask them to pass the caller’s real number through instead of overwriting it.