Skip to content

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:

  1. 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.
  2. Every address your site uses is listed. Each entry matches exactly what you write: example.com does not cover www.example.com. List both, or use *.example.com for every subdomain, plus example.com itself. Enter only the domain, without https:// or a path.
  3. Your site uses https://. The widget is only allowed inside secure pages, apart from localhost while you develop.
  4. 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.
  5. 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.
  6. 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:

  1. Ask the same question in the Playground.
  2. Open Inspect reply on the answer. It lists every passage found, with its similarity score.
  3. Then act on what you see:
What Inspect reply showsWhat to do
"This agent has no knowledge yet"Add knowledge and wait until it shows Trained
The right passage is missing or scores lowReword 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 wrongMake 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:

ReasonWhat 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 refusedUse PDF, Word (.docx), plain text or Markdown. Older .doc files are not supported.
The file is too largeFiles can be up to 20 MB. Split a larger one.
The workspace would pass its training limitThe 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 textAdd that content as a Text source
A page is blocked by your robots.txt, or by a Leave out ruleChange 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

  1. 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.
  2. 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.
  3. Check the connection is not Paused.
  4. While testing WhatsApp, the phone you write from must be on the test number's recipient list.
  5. 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.

See Privacy and your data.

Get started free — 50 credits a month