Add Widget to Your Website

Step-by-step guide to install and configure the Foxchat chat widget on your website.

Add Foxchat to any website with a single script tag. Before the widget works end-to-end, a few settings need to be in place — this guide walks through every step and calls out the mistakes that silently break things.

Prerequisites

A Foxchat account
Access to edit your website's HTML (or your CMS / site builder)

Step 1: Create a Project

In the Foxchat dashboard, click Create Project and fill in:

Project name: A label for your widget (e.g. "Foxchat" or "Foxchat Support")
Website URL: The URL where the widget will live (e.g. https://example.com)

Step 2: Connect Your Slack Workspace

Go to Slack Integration in the dashboard and click Connect with Slack. Authorize the Foxchat bot in your Slack workspace.

Important: If you skip this step, the widget will still load and visitors can still type messages — but those messages will silently never reach anyone. There is no error shown to the visitor.

Step 3: Select a Default Channel

After connecting Slack, pick which channel should receive visitor messages (e.g. #support). The Foxchat bot automatically joins the selected channel.

Important: If no default channel is selected, visitor messages are silently dropped, same as if Slack weren't connected at all.

Step 4: Enable Team Members

In the Slack integration page, scroll to the Team Members section. Toggle on at least one person who should be able to reply to visitors.

Important: If a Slack user who isn't enabled tries to reply in a Foxchat thread, they'll see a "permission denied" notice in the thread. Their reply will not reach the visitor.

Step 5: Configure Widget Settings

Go to Widget Settings in the dashboard.

Allowed Domains

The widget only loads on domains you explicitly allow. Your project's website domain is added automatically (shown with a lock icon), but you may need to add more:

Staging/preview domains: e.g. staging.example.com, my-app.vercel.app
localhost: add localhost if you want to test locally during development
Other domains: if the widget should appear on multiple sites

Subdomains are matched automatically. If you allow example.com, the widget also works on support.example.com, docs.example.com, etc.

You can add up to 10 allowed domains per project.

If the widget doesn't appear on your site, this is the most common cause. The widget silently doesn't render when the current domain isn't in the allowed list.

Appearance

Button color: Pick from presets or enter a custom hex code.
Position: bottom-right (default) or bottom-left.
Welcome message: Optional text shown in the widget header.

Path Rules (Optional)

Control which pages show the widget:

Hide on paths (default mode): List pages where the widget should be hidden. Example: /admin/*, /checkout
Show only on paths: The widget appears only on listed pages and is hidden everywhere else

Paths support the * wildcard. For example, /docs/* matches /docs/getting-started, /docs/api/auth, etc.

Step 6: Add the Embed Code

In Widget Settings, scroll to the Embed Code section and copy the snippet. It looks like this:

<script src="https://cdn.foxchat.dev/widget/loader.js" data-project-id="your-project-slug"></script>

Paste it into your website's HTML just before the closing </body> tag:

<!DOCTYPE html>
<html>
	<head>
		<!-- your head content -->
	</head>
	<body>
		<!-- your site content -->

		<!-- Foxchat Widget -->
		<script
			src="https://cdn.foxchat.dev/widget/loader.js"
			data-project-id="your-project-slug"></script>
	</body>
</html>

The data-project-id attribute is required — it tells the widget which project to connect to. If it's missing or wrong, the widget won't load.

Want to use your own button instead of the floating chat bubble? See the Custom Launcher guide to hide the default button and open the widget from your own UI.

Step 7 (Optional): Auto-Identify Logged-In Visitors

If your visitors are already logged in, you can pass their details to skip the pre-chat form. Define window.FoxchatSettings before the widget script:

<script>
	window.FoxchatSettings = {
		name: "Jane Doe",
		email: "jane@example.com",
		metadata: {
			plan: "pro",
			company: "Acme Inc.",
		},
	};
</script>
<script src="https://cdn.foxchat.dev/widget/loader.js" data-project-id="your-project-slug"></script>

The order matters — FoxchatSettings must be set before the widget script runs.

For the full API reference, field constraints, and dynamic examples, see the Visitor Identity API documentation.

Verify It Works

Open your website — a chat bubble should appear in the bottom corner
Click it, fill in your name/email, and send a test message
Check your Slack channel — a new thread should appear with the visitor's message
Reply in the Slack thread — the visitor should see your reply in real-time in the widget

Troubleshooting

Problem	Likely Cause	Fix
Widget doesn't appear at all	Current domain not in allowed domains list	Add the domain in Dashboard → Widget Settings → Allowed Domains
Widget doesn't appear at all	`data-project-id` is missing or has the wrong slug	Copy the embed code again from Dashboard → Widget Settings
Widget doesn't appear on certain pages	Path rules are hiding it	Check the path rules in Widget Settings
Clicking "Start Conversation" does nothing	Domain passes client check but fails server validation	Open browser DevTools → Console and look for a "Domain validation failed" error
Messages sent but never arrive in Slack	Slack workspace not connected	Go to Dashboard → Slack Integration and connect
Messages sent but never arrive in Slack	No default channel selected	Select a default channel after connecting Slack
Replies from Slack don't reach the visitor	The replying user isn't enabled as a team member	Enable them in Dashboard → Slack → Team Members
`window.FoxchatSettings` is ignored	Defined after the widget script	Move the `FoxchatSettings` `<script>` block before the widget script tag
Widget doesn't load on localhost	`localhost` not in allowed domains	Add `localhost` to allowed domains in Widget Settings
Widget styles look broken	Something on your page is targeting `#foxchat-widget`	The widget uses Shadow DOM for isolation — check for CSS rules like `#foxchat-widget { display: none }`

Debugging tip: Most widget errors are logged to the browser's developer console with a Foxchat: prefix. Open DevTools → Console if something isn't working.

Good to Know

Sessions last 24 hours. Visitor conversations are stored in the browser's localStorage and expire after 24 hours of inactivity. After that, a new session starts.
CSS isolation. The widget renders inside a Shadow DOM — your site's styles won't affect it and its styles won't leak into your page.
SPA support. The widget automatically detects client-side navigation (pushState / replaceState) so it works with React, Vue, Next.js, and other single-page app frameworks.
File uploads. Visitors can attach up to 3 files per message (max 2 MB each). Supported types: JPEG, PNG, WebP, GIF, and PDF.
Subdomain matching. If example.com is in your allowed domains, any subdomain (like app.example.com) is automatically allowed too.