Chapter 12
Troubleshooting
Start with the visible symptom, then narrow the problem down.
| Symptom | What to check |
|---|---|
| A menu item or bot section is missing | The menu follows your roles. Ask an Administrator or Security Admin to check the roles on your account. |
| Changes to an API are not saved, or you see “API configurations are read-only for your role” | Saved APIs need the API Integrator role. Ask an API Integrator to make the change, or ask for that role. |
| “Your role can view this bot but cannot change its design” | Your roles allow reading the bot only. Flow changes need the Bot Designer role. |
| The bot cannot be published | Open the validation report and work through each issue: one Start flow, one entry per flow, connected steps, valid branch targets, declared variables, complete translations, and a staffed department for Live Agent steps. |
| An API step follows the Failure branch | Inspect the error in the run trace. Check the workspace connection, the request path, the variables, the expected status, the response mapping, and whether the remote service is available. |
| Knowledge returns a guarded response | Confirm that a relevant, current source is ready. Test a specific question and improve the source wording. A guarded response is correct when the evidence is not sufficient. |
| A value is missing or has the wrong type | Check where the variable is declared and assigned. Review the input, API mapping, Set Variable, AI Router, or script output in the trace. |
| Untrained queries stays empty | Check that transcript storage is on in Bot settings. The list fills only from live conversations, not from the playground. |
| A trained question is still not answered | If it was added to an intent, publish the bot first. If it was added as an answer, add another answer that uses the customer’s own wording. |
| Observability shows a worker as Down or Unknown | Unknown means the worker has not reported yet; Down means it has stopped. Ask your administrator to start the workers. Without the channel worker, WhatsApp messages are not delivered. |
| A close, fallback, or inactivity flow does not run | Confirm that the flow is selected in Bot settings and is part of the published release. |
| An agent cannot claim a chat | The agent has reached their concurrent chat limit. Resolve a chat, or raise the limit under Users & agents. |
| The Agent inbox says “Agent access required” | Ask an Administrator or Security Admin to give you the Agent or Supervisor role in a department. |
| The draft works but the live bot does not | Check that the intended version was published and that the deployment is switched on. Then check the embed script or WhatsApp number and test from the real channel. |