Troubleshooting
What to check when the widget does not show, an agent cannot answer, training fails or a channel is silent.
On this page
Start from what you see. Each section below names a symptom, its usual causes in the order to check them, and what to do.
When a screen in ikazebot shows an error with a Reference, copy it (it has a copy button) and include it whenever you report the problem. It identifies the exact request in our logs.
The widget does not appear on my site
Check these in order:
- Your domain is listed. Open the agent, then Deploy → Where it runs → Allowed domains. The widget runs nowhere until at least one domain is listed.
- Every address your site uses is listed. Each entry matches exactly what you write:
example.comdoes not coverwww.example.com. List both, or use*.example.comfor every subdomain, plusexample.comitself. Enter only the domain, withouthttps://or a path. - Your site uses
https://. The widget is only allowed inside secure pages, apart fromlocalhostwhile you develop. - The snippet is on the page. Copy it again from the Deploy tab and paste it before
</body>. On a site builder, check that the custom code is published, not only saved as a draft. - The visitor is in the share that sees it. If Shown to N% of visitors is below 100%, some browsers never see the bubble by design. Set it to 100% while you test.
- You saved. Changes on the Deploy tab apply after Save widget settings.
The Preview on the Deploy tab always works, whatever your domains, so it is a quick way to check the agent itself before you check the site.
Visitors see "This assistant is not available right now"
The widget and help page deliberately show visitors the same short message for several causes, and never say which. Check, as an owner or admin:
- Credits. With none left, agents stop replying. See Settings → Usage, then buy credits or a plan.
- The agent's model. If the model is no longer offered, the agent's settings say model unavailable. Choose another model.
- The help page is off. The address
/help/<agent-id>works only while Hosted help page is on, on the Deploy tab.
Visitors see "Sign in on this site to chat"
Only verified visitors is on in the agent's Deploy tab, so anyone your site has not signed in is refused. Either turn it off, or make sure your site sends the visitor's identity. See identity verification.
The agent says it does not know, or answers wrongly
The agent answers from your knowledge only, and says it does not know when nothing matches well enough. Find out which case you are in:
- Ask the same question in the Playground.
- Open Inspect reply on the answer. It lists every passage found, with its similarity score.
- Then act on what you see:
| What Inspect reply shows | What to do |
|---|---|
| "This agent has no knowledge yet" | Add knowledge and wait until it shows Trained |
| The right passage is missing or scores low | Reword the source in your customers' words, or add a Q&A pair for that exact question |
| The right passage is there, but the answer is still wrong | Make the instructions more specific, or compare another model |
Also check that the source is Trained, not still training or Failed.
A knowledge source failed or skipped pages
The source shows Failed with a reason, or a website lists pages as Skipped with why. The common reasons:
| Reason | What to do |
|---|---|
| The PDF has no text layer (usually a scan) | Export a PDF with selectable text, or paste the text as a Text source |
| The file type is refused | Use PDF, Word (.docx), plain text or Markdown. Older .doc files are not supported. |
| The file is too large | Files can be up to 20 MB. Split a larger one. |
| The workspace would pass its training limit | The limit covers all agents together. Remove sources you no longer need, or move to a plan with more. |
| A page needs JavaScript to show its text | Add that content as a Text source |
A page is blocked by your robots.txt, or by a Leave out rule | Change the rule if the page should be learned from |
I cannot create an agent, invite someone or add something
These limits come from your plan, and the message names the limit you reached:
- Agents, actions, seats and training size are limited per workspace. Seats count members and pending invitations, so revoking an old invitation frees one.
- Only owners and admins can create and change agents, knowledge, actions and channels. Ask an owner or admin to change your role.
- You can own up to three workspaces. Joining others by invitation has no limit.
An invitation or email did not arrive
- Verification email: on the sign-in or sign-up page, use the button to send it again. Check your spam folder.
- Invitation: an owner or admin can resend it from Settings → Members → Invitations. If it has expired, send a new one.
- Wrong address: the person must sign up or sign in with the address the invitation was sent to. Revoke it and invite the right address otherwise.
WhatsApp, Messenger or Instagram are silent
- On the connection in Settings → Messaging channels, select Run checks. It goes through the token, app secret, subscription and webhook in the order to fix them, and says what to do for each problem.
- Read What Meta sent lately. A wrong app secret or a message for another number shows up there, so it does not look like silence.
- Check the connection is not Paused.
- While testing WhatsApp, the phone you write from must be on the test number's recipient list.
- If every check passes, switch your Meta app from Development mode to Live. Meta does not send some webhooks in Development mode.
The full walkthrough is in Messaging channels.
Our team's replies on WhatsApp, Messenger or Instagram are marked failed
Meta only lets a business reply freely for 24 hours after the customer's last message. Replies sent later are refused and marked failed. Once the customer writes again, you can reply. See Meta's 24-hour window.
The agent stopped replying in one conversation
- Your team took it over. While a person has the conversation, the agent stays silent. Select Hand back to the agent in the Inbox.
- The spam check paused it. The Inbox shows Resume: not spam on the conversation; resume it if that was a mistake.
- A guardrail stopped the message. The Inbox marks replies sent by a guardrail. If the Only talk about topics are too narrow, widen them on the Deploy tab.
- The visitor sent too much. Each visitor may send 10 messages a minute; after that they see your rate-limit message until a minute has passed.
API requests fail
Every error says why in its code. The common ones are API_KEY_INVALID (a missing, unknown or revoked key), API_SCOPE (the key lacks that permission or agent), API_NOT_ON_PLAN (the API needs a paid plan) and API_RATE_LIMITED (over 60 requests a minute). The full table is in the REST API guide.
I cannot delete my account or export my data
- Deleting your account is refused while you are the only owner of a workspace; the message names it. Make someone else an owner, or delete that workspace, first.
- An export is refused while another is still being prepared, or after three in a day. Wait for the email, or try again the next day.
Related
- Frequently asked questionsShort answers about agents, knowledge, channels, credits, your data and your team.
- Test in the playgroundTry changes without saving, compare two models and inspect exactly what a reply was given.
- WhatsApp, Messenger and InstagramConnect your Meta app so an agent answers customers in their messaging apps.