FAQ & troubleshooting
Short answers to the questions that come up most often when you set up and run Iterochat. Each one links to the page with the full story.
The widget isn't showing on my site
Start with the embed snippet. The widget loads from a single <script> tag that should sit immediately before the closing </body> tag on every page where you want chat. If the bubble isn't appearing, check that:
- the snippet is actually on the page (view source and look for
widget.js), - it carries your real
data-widget-key(thewk_...key from Settings → Website Widget, not a placeholder), and - there's only one copy of the snippet on the page.
A missing or placeholder data-widget-key is the most common cause. The key is what ties the widget to your organization; without the correct one, the widget can't connect. Copy the snippet straight from the Settings card so the right key is already filled in.
The widget renders inside its own isolated container and pulls in no external dependencies, so a styling or script conflict with your site almost never keeps it from loading. See The chat widget for the full embedding walkthrough.
The AI isn't answering from my knowledge base
The AI only answers from the documents in your knowledge base: it won't make facts up. If it's saying it doesn't have an answer, that topic probably isn't covered yet, or isn't covered clearly.
Open the Knowledge Base tab (owners and admins see it) and check that a document actually contains the specific answer the customer needs: the amounts, steps, and conditions, not just a pointer to them. Changes take effect on the next customer message, with no publish step or redeploy, so you can add a document and test again right away. Your escalation queue is the best guide to what's missing: each handed-off question the AI couldn't answer is usually a gap to fill. See Knowledge base.
The AI replied in the wrong language
Language is automatic. The AI detects the customer's language and matches it, across a wide range of languages and including code-mixed writing like Banglish. There's no language setting to configure, and you don't need a separate knowledge base document per language; the AI answers in the customer's language from whatever language you wrote your content in. That includes short suggested questions: the reply follows the language of that message, not the language of your knowledge base.
If a reply still comes back in an unexpected language, it's usually because the customer's message was short or mixed enough to be read as another language. Custom AI instructions can't change this: language rules can't be overridden by instructions. See AI configuration.
No escalations are reaching my agents
If conversations that should reach a person aren't showing up in your queue, the most likely reason is AI-only mode. While it's on, the AI handles every conversation itself and never escalates, by design. Check the AI-Only Mode card in Settings: it may be on manually, or a schedule may have switched it on automatically (for example, outside your support hours). The card always shows whether AI-only mode is currently active.
Outside AI-only mode, the AI escalates on knowledge gaps, explicit requests for a human, sensitive intents (refunds, complaints, account or payment issues), and clear customer frustration. If you expect escalations on a topic but aren't seeing them, confirm AI-only mode is off and that an agent is watching the queue. See AI configuration for the full list of triggers.
How do I add a photo to my replies?
In the sidebar, click your face and name (the row labeled Account). On the Profile card, upload a JPEG, PNG, or WebP (up to 2 MB). It saves immediately. Customers see it on new replies; older replies keep initials. This is your face, not the AI's — that one is under Settings → AI identity. See Your profile photo.
How do I change what the AI sounds like
Open the AI Instructions tab and write titled instruction blocks describing the tone, personality, and brand voice you want. Enabled blocks apply live to every new conversation, and you can toggle blocks on or off without deleting them.
Instructions steer tone, persona, and wording only. They can't override the AI's language rules, its rule that it answers only from your knowledge base, or its escalation triggers. Those stay in place no matter what you write.
See AI configuration.
Do changes take effect right away?
Yes. Knowledge base edits, AI instructions, suggested questions, and AI-only mode all apply on the next customer message. There's no publish step, redeploy, or waiting period. The AI reads the current state of your settings each time it answers.
What happens after the AI hands off to a person?
The AI stops responding the moment a conversation is escalated, and writes a short handoff summary for your team. From that point the customer is talking to a human agent, and the AI won't speak over them. See Introduction for the full conversation lifecycle.
How do I connect WhatsApp, Messenger, or Instagram?
Owners and admins open Settings → Integrations, then choose Connect WhatsApp or Connect Facebook Page. Follow the prompts to link a number or Page. Linked Instagram professional accounts can be included when you connect a Page. Connected channels share the same Conversations queue as website chat. See WhatsApp channel, Messenger channel, and Instagram channel.
If a Messenger Page stops receiving new messages after a long outage, reconnect it from Integrations.
How do I get escalation alerts outside the dashboard?
Browser push and in-app chimes only reach people who have the dashboard open or subscribed on that device. For paging, on-call, or custom routing, owners and admins can set up outbound webhooks under Settings → Notifications (outbound webhooks).
Add your HTTPS endpoint, copy the signing secret, enable escalation.created (and optionally escalation.unclaimed), and use Send test event to verify your receiver. The full integration guide, signature verification code, and payload reference are in the webhooks doc.
How do I report a bug or request a feature?
Iterochat is in active development, and input from the teams using it shapes what comes next. Open the Feedback section in your dashboard, choose whether you are reporting a bug or requesting a feature, add a short title and a description, and send it. Anyone on your team (owners, admins, and agents) can submit, and owners and admins can review everything their team has sent in.
Glossary
- Organization: your workspace in Iterochat. It holds your widget, knowledge base, team, and conversations. One person can belong to more than one organization.
- Widget key: the
wk_...string in Settings → Website Widget that ties the embedded widget to your organization. It's already baked into your embed snippet. - Escalation: the handoff from the AI to a human agent when the AI shouldn't answer on its own (a knowledge gap, a request for a person, a sensitive intent, or clear frustration).
- Handoff summary: the short, two-to-four-sentence recap the AI writes when it escalates, so the agent who picks up the conversation knows what the customer needs and what's already been tried.
- AI-only mode: a setting that has the AI handle every conversation on its own without escalating to a human. Useful overnight, on weekends, or while piloting.