The chat widget
The Iterochat widget is the chat experience your customers actually touch: a floating bubble on your site that opens into a conversation. The AI answers from your knowledge base, and when a question needs a person, the conversation hands off to one of your agents without the customer noticing a seam.
This page covers two things:
- How to embed the widget on your site.
- What your customers see when they use it.
Embedding
You add the widget with a single <script> tag. Copy it from Settings → Website Widget (it already contains your key) and paste it on your site:
<script
src="https://widget.iterochat.com/widget.js"
data-widget-key="wk_your_key_here"
async>
</script>
A few things this gives you:
- Always current. The script loads from
widget.iterochat.com, so it stays up to date automatically. You never host or update the file yourself. - Self-contained. No frameworks, no jQuery, no external CSS or fonts to add.
- Isolated. It mounts in its own isolated container, which keeps its markup and styles separate from your page (and your page's styles out of it), so it looks and behaves the same on any site.
Only the data-widget-key attribute is required. The async attribute just lets the script load without blocking your page. There's nothing else to configure in the tag.
What your customers see
When the script loads, a chat bubble appears in the bottom-right corner of every page it's on. Clicking it opens the chat panel (about 380px wide on desktop, full-height on mobile). The first time, customers are asked for their name, then they're chatting.
Inside the panel, customers get:
- Distinct message styles for the customer, the AI assistant (labeled "AI Assistant"), and human agents (shown with the agent's name).
- A typing indicator while the AI is composing a reply ("Replying…") or while an agent is typing ("Agent is typing…").
- A handoff line when a person joins, such as "You're now chatting with Alice", so the customer knows they're now talking to a human.
- An unread badge on the bubble when a new message arrives while the panel is closed.
- A "Powered by Iterochat" link under the input.
When a conversation is resolved, the customer is invited to rate the experience before the panel returns to its starting state.
Customize the widget
In Settings → Widget Appearance, you can match the chat widget to your brand:
- Primary color sets the launcher, the chat panel header, and accent color.
- Position places the launcher in the bottom-right or bottom-left corner.
- Header title is the name shown at the top of the chat panel.
- Greeting is the welcome message visitors see when they open the chat.
A live preview updates as you edit, so you can see the result before publishing. Switch the preview between Desktop and Mobile to check each device, and between the Launcher and Conversation views to inspect both the closed launcher and the open chat panel. Your changes go live on your site after you select Save appearance.
Appearance changes apply on their own. There is no need to re-embed the widget or change your snippet after you save.
Fit the widget to your site
You can size and place the chat launcher separately for desktop and mobile, so it never covers your own buttons. Use the Desktop and Mobile toggle above the preview to choose which device you are editing, then set:
- Launcher size: choose small, medium, or large. Set it per device.
- Offset: nudge the launcher up or in from the edge. Desktop and mobile have their own offsets, so you can give each one the spacing it needs. (The left or right position is shared across both.)
- Hide on mobile: hide the chat widget entirely on phones if you prefer. The preview shows a "Hidden on mobile" note so you can confirm the result.
- Auto-hide while scrolling: on phones, the launcher can slide away as a visitor scrolls down and return when they scroll up, keeping the screen clear while they read.
The widget also keeps clear of phone safe areas (notch and home bar) automatically.
If you want to start over, Reset to defaults returns every appearance option to its original settings (you still need to Save appearance to apply it).
Show the widget only on certain pages
By default the widget appears on every page that has your snippet. From Settings, you can narrow that down without editing your site's code:
- Show everywhere. The default. The widget appears on all pages.
- Show only on these pages. The widget appears only on pages you list.
- Hide on these pages. The widget appears everywhere except the pages you list.
You describe pages with a path and an optional wildcard *:
/pricingmatches only the pricing page./blog/*matches every page under/blog, such as/blog/launch-day. It does not match the/blogpage itself, so add/blogas a second pattern if you want that too.*matches every page.
Patterns match the page path only (the part after your domain). Anything after a ? or # is ignored, and matching is not case-sensitive. Use Test a URL to paste any address and see whether the widget would show there before you save.
Changes take up to a minute to reach your site.
If your site loads new pages without a full page reload (for example, a single-page app), the widget checks its page rules once when it first loads and does not re-check on later in-page navigation. It reliably follows your rules on any site where each page is a normal full load.
To show the widget on your home page only, choose Show only on these pages and add a single pattern: /.
Languages
The widget needs no language setting. The AI detects the language of each incoming message and replies in the same language, written in that language's own script. It handles a wide range of languages out of the box, and it is especially strong with code-mixed writing, where customers blend two languages in one message. Banglish (romanized Bangla mixed with English) is the clearest example, and the same applies to styles like Hinglish or Roman Urdu. A customer who writes in Banglish gets a Banglish answer back, and one who writes in another language gets a reply in that language.
This is handled entirely by the AI from the customer's own words. There is nothing for you to configure, and a single widget serves every customer whatever language they write in.
The widget's own buttons and labels (for example "Start Chat" or "End chat") are currently in English. The detection above applies to the conversation itself, meaning the AI's and agents' replies, which is what customers read and respond to.
Suggested questions
When a customer opens the widget for the first time in a conversation, it can show a few tappable chips: common questions you choose. Tapping one sends that question as the customer's first message, which gives people an easy way to start.
You configure these under Settings → Suggested Questions:
- Up to four chips, 120 characters each.
- Remove all of them to hide the chips entirely.
- Changes apply to new conversations, with no need to re-embed the widget.
See AI configuration for more on shaping what the widget offers.
Pre-chat form
You can ask visitors for their details before they start chatting, so you know who you are talking to and can follow up later. Set this up under Settings → Pre-chat form:
- Turn on Collect visitor info before chat to show the form. With it off, visitors go straight into the conversation.
- For each field (Name, Email, and Phone), choose one of three options:
- Off: the field is not shown.
- Optional: the field is shown, but the visitor can skip it.
- Required: the visitor must fill it in before sending their first message.
Select Save pre-chat form to apply your choices. Changes apply to new conversations, with no need to re-embed the widget.
Whatever a visitor shares comes through to your team: their email and phone appear at the top of the conversation, so an agent can reach them without asking again.
Reliability
The widget is built to survive the messiness of real browsing:
- Sessions persist. The conversation is stored in the browser, so a refresh, a navigation to another page, or opening a second tab keeps the same conversation going rather than starting over. Messages stay in sync across tabs of the same session.
- It reconnects on its own. If the network drops, the widget shows a quiet "Reconnecting…" notice and retries with increasing back-off (waiting 1, 2, 4, 8, then up to 30 seconds between attempts) until it's back. Customers aren't shown error messages or technical details.
- Resolved conversations lock. Once a conversation is marked resolved, the input is disabled and the customer is offered the rating prompt, so they can't accidentally keep typing into a closed ticket. Opening the widget again starts a fresh conversation.
Troubleshooting
If something looks off, work through these first:
- The widget doesn't appear. Check that the snippet is on the page (pasted before
</body>) and that thedata-widget-keyvalue is your real key from Settings. With no key, or a blank one, the widget will not mount at all. - Styling looks wrong, or it clashes with your site. This shouldn't happen, because the widget is fully isolated from your page: your site's CSS can't reach inside it and its styles can't leak out. If you see a conflict, confirm you haven't added a second, conflicting chat script.
- Replies come back in the wrong language. Language is driven by what the customer types, not a setting. If answers feel off, the fix is usually in your AI setup and knowledge base. See AI configuration.
A placeholder or wrong widget key is the most common reason the widget silently fails to load. Make sure the data-widget-key is the exact value copied from Settings → Website Widget (it starts with wk_) and not the wk_your_key_here example from the docs. If a session can't be authenticated, the widget will quietly start a new conversation rather than show an error.