Installation
The embed snippet for the KonvoAI chat widget, and the caveats worth knowing before you ship it.
Installing the widget is one <script> tag. Paste it once into your site's HTML
and the launcher appears on every page that includes it.
The embed snippet
Copy the snippet from your channel's settings in the KonvoAI dashboard. It looks like this:
<script
src="https://widget.konvoai.com/widget.iife.js"
data-konvoai-channel="widget_xxxxxxxxxxxxxxxx"
async
></script>Two things matter:
data-konvoai-channelcarries your channel's public identifier. It is the only attribute the widget reads, and it is required — without it the widget refuses to render. This value is not a secret; it is meant to live in your page's HTML.asynclets the browser load the widget without blocking the rest of your page. We recommend keeping it.
Where do I put it?
Anywhere in the page works — <head> or just before </body>. The widget
waits for the DOM to be ready before it renders, so placement doesn't change
behavior. Add it to a shared layout/template so it loads on every page.
Verify it loaded
After deploying, open your site and look for the launcher in the corner. If it doesn't appear, open your browser's developer console:
Caveats
Content Security Policy
If your site sends a Content-Security-Policy header, allow the widget to load
its script, talk to KonvoAI, and render its (shadow-scoped) styles:
script-src— the host servingwidget.iife.js.connect-src— the KonvoAI endpoint the widget connects to, including thewss:origin for its live connection.style-src— the widget injects its stylesheet inline into its shadow root, so'unsafe-inline'(or a matching nonce/hash strategy) must be permitted.
The exact hostnames are shown alongside the embed snippet in your dashboard.
One widget per page
Embed the snippet once. The widget renders into a fixed container
(#konvoai-widget); adding the script more than once on the same page is not
supported and can produce duplicate or broken UI.
Browser storage
The widget uses localStorage and sessionStorage to remember the visitor and
their session (see Sessions & identity). In contexts
where storage is unavailable or wiped between loads — private/incognito windows,
strict third-party-storage blocking, some embedded webviews — the widget still
works, but the visitor isn't remembered across reloads and the verification step
runs again each time.
Mobile
On narrow screens (≤ 640px) the chat panel opens full-screen rather than as a floating panel, so it stays usable on phones. No configuration needed.
Single-page apps
The widget persists across client-side navigations — you don't need to re-run the snippet when your router changes the route. It also notices page changes so your agents can see which page a visitor is on during an active chat.
Don't reposition it with your own CSS
Because the widget lives in a shadow root, your stylesheets can't reach inside it — and you shouldn't try to move or restyle it from the host page. Use the appearance settings in the dashboard for position, colors, and size.