Site Widget

This guide covers adding the chat widget to your website, managing its appearance, and what data the widget collects and how.

Adding It to Your Site

1. Open Admin Panel → Integrations → Web.
2. Copy the ready-made <script> snippet.
3. Paste it into your site just before the closing </body> tag.

That's it — the widget appears in the bottom-right corner. The snippet can go on every page; the bundle is under 60 KB (gzip) and does not block page load.

For iframe-embedding scenarios use the variant under Integrations → Embedded.

Managing the Appearance

The widget's look is managed from the panel, not from code: every change in the Bot Appearance screen (colors, bot name, welcome message, logo, suggested questions) saves automatically and reaches live widgets without any code change.

The mechanism behind this: on open, the widget fetches its configuration from the public GET /api/widget-config?token=<site-token> endpoint. The response is cached for 60 seconds; a change you make in the panel reaches all visitors within a minute.

Behavior

• Welcome — when opened, the widget shows the welcome message and (if defined) suggested questions; a visitor can start the conversation by clicking one.
• Bot replies are plain text; links are made clickable.
• Human handoff — the bot hands conversations it cannot resolve to a human agent; the visitor continues with the agent in the same window.
• Offline handling — when the connection drops, the widget shows its status and resumes where it left off once back online.
• A conversation continues where it left off in the same browser, even after the tab is closed.

Campaign Tracking (Attribution)

When a conversation is first opened, the widget captures marketing attribution and attaches it to the conversation; the data shows up in the panel and (if configured) in your CRM/lead flow:

• The utm_source, utm_medium, utm_campaign parameters
• The page the visitor came from (referrer) and the page where they started the conversation (landing page)

First-touch logic applies: even if the visitor arrives via a campaign link and starts the conversation on another page, the campaign data from their first entry is preserved (for the lifetime of the tab).

Privacy

• No cookies, no fingerprinting. Only page-URL-level data is collected.
• Page addresses are recorded without query strings (domain + path only) — parameters that might carry session tokens or emails in URLs are never collected.
• The widget inside the panel preview collects no attribution at all — preview traffic never counts as visitor data.
• All values are clipped to a length limit.

Troubleshooting

Symptom	Check
Widget doesn't appear	Is the snippet before </body>? Any errors in the browser console?
Widget opens but the bot doesn't answer	Is an API key entered in Settings → Model, and does Test pass?
Color change not visible	Wait out the 60 s cache; refresh the page.
Messages don't reach Chatwoot	Inspect the event flow in Panel → Webhook Events.