# 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](/content/docs/custom-launcher/index.html) 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](/content/docs/visitor-identity/index.html) documentation.

## Verify It Works

1. Open your website — a chat bubble should appear in the bottom corner
2. Click it, fill in your name/email, and send a test message
3. Check your Slack channel — a new thread should appear with the visitor's message
4. 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.