---
title: "Web widget"
url: "/channels/web-widget"
description: "Embed the chat widget on your website, control how it looks, and restrict which domains may load it and who may chat."
productArea: channels
audience: ["business-user", "developer"]
tags: ["channels", "widget"]
lastReviewed: 2026-09-11
---

# Web widget (/channels/web-widget)





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 [#adding-it-to-your-site]

1. Open the agent's **Sandbox** tab.
2. Configure the appearance and welcome message.
3. Copy the embed snippet.
4. 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 [#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](/reference/interaction-counting) before enabling uploads on a
high-traffic site.

## Allowed origins [#allowed-origins]

<Callout type="warn">
  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.
</Callout>

Add every domain that should be able to load the widget, including staging domains. Requests
from anywhere else are rejected.

## Restricting who can chat [#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](/channels#access-control) for how the two modes work.

<Callout type="warn">
  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.
</Callout>

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 [#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](/channels/demo-links).

## For developers [#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](/build/widget-sdk).

## Troubleshooting [#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](/knowledge) for supported types      |

## Related pages [#related-pages]

* [Channels overview](/channels)
* [Widget SDK](/build/widget-sdk)
* [Interaction counting](/reference/interaction-counting)