# Foxchat — Complete Installation Guide > This document is designed for AI coding assistants. It contains everything needed to add the Foxchat chat widget to any website. Foxchat is a lightweight, affordable alternative to Intercom, Crisp, and Drift — built for indie hackers, startups, and small teams who live in Slack. Visitors chat through a bubble on your site, messages go to Slack instantly, and your team replies from Slack. The visitor sees the reply in real-time on the website. No bloated dashboards, no seat-based pricing. Starting at $10/month. --- ## Embed Code The universal embed code for all frameworks: The `data-project-id` attribute is required. Replace `YOUR_PROJECT_SLUG` with the project slug from the Foxchat dashboard. If the user does not have a Foxchat account yet, direct them to: https://app.foxchat.dev/signup --- ## Account Setup Steps After signing up, the user needs to complete these steps in the Foxchat dashboard (https://app.foxchat.dev): 1. **Create a project** — give it a name and website URL. The project slug is auto-generated from the name. 2. **Connect Slack** — go to Slack Integration and click "Connect with Slack". Without this, visitor messages silently go nowhere. 3. **Select a default channel** — pick which Slack channel receives visitor messages (e.g. #support). Without this, messages are silently dropped. 4. **Enable team members** — in the Slack integration page, toggle on people who should be able to reply. Unenabled users who reply in Slack threads will get a "permission denied" notice. 5. **Configure allowed domains** — in Widget Settings, the project's website domain is added automatically. Add any additional domains (staging, localhost for dev, etc.). The widget silently won't render on unlisted domains. --- ## Framework-Specific Installation ### Plain HTML File to edit: `index.html` (or any HTML file) Add before ``: ```html ``` ### React / Vite File to edit: `index.html` (in project root or `public/`) Add before ``: ```html ``` Note: In Vite projects, `index.html` is the HTML shell. The widget script goes here, not in a React component. ### Next.js — App Router File to edit: `app/layout.tsx` (the root layout) Add the `Script` import and component inside ``: ```tsx import Script from "next/script"; export default function RootLayout({ children }: { children: React.ReactNode }) { return ( {children} ``` The `is:inline` attribute is required — it prevents Astro from bundling the script. ### Remix File to edit: `app/root.tsx` Add the script tag inside the `` of your root component: ```tsx export default function App() { return ( ``` ### Nuxt File to edit: `nuxt.config.ts` Add the script to the app head configuration: ```ts export default defineNuxtConfig({ app: { head: { script: [ { src: "https://cdn.foxchat.dev/widget/loader.js", "data-project-id": "YOUR_PROJECT_SLUG", defer: true, }, ], }, }, }); ``` ### Svelte / Vite File to edit: `index.html` (in project root) Add before ``: ```html ``` ### SvelteKit File to edit: `src/app.html` Add before ``: ```html ``` ### WordPress Option A — Edit theme file: `footer.php` in your active theme directory. Add before ``: ```php ``` Option B — Use a plugin like "Insert Headers and Footers" (WPCode) and paste the script tag in the footer section. ### Shopify File to edit: `theme.liquid` (in your active theme under Layout) Add before ``: ```liquid ``` ### Webflow No file to edit. Go to Project Settings > Custom Code > Footer Code and paste: ```html ``` Then publish the site for changes to take effect. --- ## Visitor Identity API (Optional) If visitors are already logged in, you can auto-identify them so they skip the pre-chat form. Define `window.FoxchatSettings` before the widget script: ```html ``` ### Fields | Field | Type | Required | Description | |----------|--------------------------|----------|-----------------------------------------------------| | name | string | No | Visitor's display name (max 200 characters) | | email | string | No | Visitor's email address (max 320 characters) | | metadata | Record | No | Custom key-value pairs (max 20 keys, 1000 chars/value) | At least `name` or `email` must be provided for auto-identification. If neither is set, the pre-chat form is shown as usual. ### Important - The `window.FoxchatSettings` script MUST appear before the widget script tag. Order matters. - All metadata values must be strings. Convert numbers/booleans to strings (e.g. `"123"`, `"true"`). - If the widget has already loaded with an anonymous session, `FoxchatSettings` won't retroactively update the visitor. - Visitor sessions last 24 hours in localStorage. When a session expires, a new visitor is created from the current `FoxchatSettings`. --- ## Troubleshooting | Problem | Likely Cause | Fix | |--------------------------------------------|----------------------------------------------------|--------------------------------------------------------------| | Widget doesn't appear at all | Domain not in allowed domains list | Add domain in Dashboard > Widget Settings > Allowed Domains | | Widget doesn't appear at all | data-project-id missing or wrong slug | Copy embed code from Dashboard > Widget Settings | | Widget doesn't appear on certain pages | Path rules are hiding it | Check path rules in Widget Settings | | Clicking "Start Conversation" does nothing | Domain fails server validation | Check browser DevTools console for "Domain validation failed"| | 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 | Replying user isn't enabled as team member | Enable them in Dashboard > Slack > Team Members | | window.FoxchatSettings is ignored | Defined after the widget script | Move FoxchatSettings script before the widget script tag | | Widget doesn't load on localhost | localhost not in allowed domains | Add localhost to allowed domains in Widget Settings | Debugging tip: Widget errors are logged to the browser console with a "Foxchat:" prefix. --- ## Important Notes - **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. - **Sessions**: Visitor sessions last 24 hours and are stored in localStorage. After 24 hours of inactivity, a new session starts. - **File uploads**: Visitors can attach up to 3 files per message (max 2 MB each). Supported types: JPEG, PNG, WebP, GIF, PDF. - **Subdomain matching**: If `example.com` is in allowed domains, any subdomain (like `app.example.com`) is automatically allowed too. - **Path rules**: You can hide the widget on specific paths (e.g. `/admin/*`, `/checkout`) or show it only on specific paths. Wildcard `*` is supported. --- ## Links - Website: https://foxchat.dev - Dashboard: https://app.foxchat.dev - Signup: https://app.foxchat.dev/signup - Docs: https://foxchat.dev/docs/add-widget-to-website - Visitor Identity API docs: https://foxchat.dev/docs/visitor-identity