Web widget
Embed the chat widget on your website, control how it looks, and restrict which domains may load it and who may chat.
The web widget is a chat window you embed in your website. It is the default way to put an agent in front of customers and the only channel available on every plan.
Adding it to your site
- Open the agent's Sandbox tab.
- Configure the appearance and welcome message.
- Copy the embed snippet.
- Paste it into your site's HTML, before the closing
</body>tag.
The widget loads in an isolated container, so it will not inherit or interfere with your site's styles.
Configuration
From the Sandbox tab you can set the widget title and subtitle, branding and colours, whether file upload is enabled, whether voice notes are enabled, and links to your privacy policy and terms.
Widget Description is a short message shown on the widget's welcome screen — write it for the customer opening the chat, not for yourself. It's separate from the agent's own description (set on the Identity tab), which is used internally for routing, delegation and system context and is never shown to a customer. Leave Widget Description blank and the welcome screen falls back to the internal description instead.
Attachments count towards usage — see interaction counting before enabling uploads on a high-traffic site.
Allowed origins
The widget only works on domains listed in the agent's allowed origins. This is what stops someone embedding your agent on their own site and spending your allowance. If the widget does not appear on your site, this is the first thing to check.
Add every domain that should be able to load the widget, including staging domains. Requests from anywhere else are rejected.
Restricting who can chat
Allowed origins control which sites may load the widget. To control which people may talk to the agent once it has loaded, use the Allow List and Deny List tabs on the widget channel. See access control for how the two modes work.
On the widget, only contact entries take effect. A data table row or whole-table entry does not authorise a widget visitor, so a widget channel set to Restricted with only data table entries turns everyone away.
Separately from any list you configure, KlicForge checks public widget traffic for automated abuse before a visitor's first message. There is nothing to set up and nothing for a genuine visitor to solve.
A visitor arrives with whatever identity your page supplies through the SDK, and a browser can send anything. So a widget allow list is a convenience for a small, known audience, not a security boundary. When only certain people should reach an agent, put it on Telegram or WhatsApp — the messaging platform confirms who the sender is — or gate the page the widget sits on with your own login.
Testing
Use the agent's Sandbox tab to talk to the agent exactly as a visitor would, without embedding anything.
From the same screen, Share demo creates a public link a prospect can open before you embed anything on their site. See public demo links.
For developers
The widget is also available as an npm package and a CDN bundle, with a JavaScript API for opening, closing, sending messages and listening to events. See the widget SDK.
Troubleshooting
| Symptom | Likely cause |
|---|---|
| Widget does not appear | The site's domain is missing from allowed origins |
| Widget appears but never replies | Agent status is draft or inactive |
| Widget looks wrong on your site | Check the container is not inside an element with overflow: hidden |
| Every visitor is turned away | The channel is Restricted and the allow list holds only data table entries |
| Uploads rejected | File type or size limit — see knowledge for supported types |