Platform Guide

Everything SwiftChat can do — from adding your first site and fetching its brand, to customising the widget, publishing a Help Center and managing plans.

Overview

SwiftChat is a self-hosted AI customer-support platform: a RAG engine trained on your content, an embeddable chat widget, a public Help Center, human handoff and lead capture — managed from one dashboard.

Sites — each site is an isolated knowledge base + widget configuration.
Widget — one script tag embeds chat on any website.
Help Center — browsable inside the widget or as a public portal.
Dashboard — sites, conversations, handoffs, analytics, team and platform settings.

Adding a site

From Sites → + Add, choose one of three modes:

Crawl Website — paste a URL; the crawler indexes pages automatically.
Upload Documents — knowledge from files only, no website crawl.
Both — crawl the site and upload documents together.

While creating, click Fetch brand info to preview detected branding — or skip it and it fetches automatically on create.

Brand detection

Brand detection reads the site's real homepage (rendered through a headless browser for SPAs) and extracts:

Site name and detected language
Favicon / touch icon — used as the site thumbnail and widget avatar
Brand colour palette — the primary colour is applied to widget and Help Center
Suggested questions in the detected language, built from real page headings

On an existing site, use Fetch Brand in the site actions row. The preview shows exactly what will be applied before you confirm. Applying writes the favicon, primary colour, avatar, Help Center locale and quick prompts — it replaces the current values for those fields.

Embedding the widget

Copy the embed snippet from the site's Embed tab and paste it before </body> on any website, SPA or store:

<script src="https://your-host/widget/chatbot.js"
        data-site-id="YOUR_SITE_ID"
        data-api-url="https://your-host"></script>

All configuration is managed from the dashboard — no code changes or redeploys needed on the target site.

Website crawling

The crawler follows links within your domain, respects robots.txt and sitemaps, and stores each page's text for retrieval.

SPA support — pages whose static HTML is too thin are re-rendered through headless Chromium automatically (set CRAWLER_JS_RENDER=true).
Re-crawl — refresh content any time from the site actions, or schedule automatic re-indexing under Schedule.
Failures — a crawl that finds no readable content reports the reason (e.g. JS-rendered shell) directly on the site row.

Online shops: product cards

For e-commerce sites, the crawler builds a product catalog automatically — from schema.org Product data, Open Graph product tags, or (for custom shops) product pages and listing cards with a title, price and image. When a reply mentions a product by name, the widget renders a product card (photo, name, price) that opens the product page on click. Re-crawl after adding products; disable under Behavior → Show product cards if unwanted.

Documents & text

Add Docs accepts PDF, DOCX, TXT, MD, CSV, PPTX, XLSX and HTML (up to 50 MB each). Files are parsed, chunked and indexed for retrieval. Free-text blocks and the shared Business information block work the same way — one edit re-indexes automatically.

Video knowledge Advanced

Paste a video URL in the upload modal and SwiftChat pulls its text into the knowledge base:

YouTube — fetches the caption transcript (manual captions preferred over auto-generated; English/Portuguese preferred when both exist).
Other video pages — uses declared subtitle tracks when available, otherwise the page's title and description.

The transcript becomes a normal knowledge document — the bot can answer anything covered in the video, with the video listed in Knowledge.

Q&A overrides

Fix a single answer without touching the rest of the knowledge base. Add a question and its correct answer; it takes priority over generated responses. Manage them under Q&A in site settings — useful for pricing, policies and anything the bot gets wrong.

Business info

A reusable context block (address, hours, policies, tone of voice) injected into every conversation — set once per site, applies to all answers.

Appearance

The Appearance tab customises everything visual, with a live on-page preview:

Themes — six presets: Light, Light Accent, Light Soft, Pattern Light, Pattern Accent and Dark.
Sections — independent colour controls for Header, Chat area, Message field and Footer, plus font family.
Agent profile — display name, caption/status line, avatar image and online indicator.
Welcome — welcome message and quick-prompt suggestion chips.

Launcher & behaviour

Launcher — icon, text label or combined styles; custom icon image; position (left/right) with pixel offsets; window size and open mode.
Behaviour — auto-open delay, proactive trigger messages by page/time/scroll, message sounds and typing indicator.

Visibility rules

Show the widget only where it belongs: page-URL targeting, device targeting (desktop/mobile) and schedule windows (e.g. business hours). Off-hours visitors can see an offline form instead.

Custom CSS / JS

Inject your own CSS and JavaScript into the widget from Appearance → Advanced — deep integration without forking the widget code.

Help Center portal

Each site can publish a full knowledge base: categories with icons, articles with rich content, and AJAX live search. Visitors browse it inside the widget's Help tab or on the public portal at /hc/your-site.

Manage content — create/edit categories and articles from the Help Center tab; pick or upload category icons.
Locales — publish the same portal in multiple languages with a per-visitor language selector.
Appearance — portal title, header text, brand colour, logo (also used as favicon) and social links.

See it live on our own portal: agent.swiftapps.cloud/hc.

Templates

Two layouts ship with the portal: Classic (hero search header) and Documentation (sidebar navigation). Switch any time in Help Center settings — visitors can preview both on the SwiftChat Help Center.

Custom domain Advanced

Serve the portal on your own subdomain, e.g. help.yourcompany.com. Create a DNS record pointing to your SwiftChat host, then set the custom domain in Help Center settings — the portal serves at the domain root.

Inbox & analytics

Conversations lists every chat with the full transcript; Analytics shows chat volume, top questions, satisfaction ratings and feedback trends per site.

Human handoff

When AI confidence drops or a visitor asks for a human, the conversation enters the Handoffs queue. Agents claim threads, see the full AI transcript and reply live. Handoff requires assigned agents — the Live Agent button hides automatically when none are configured. Off-hours requests become offline email tickets.

Lead capture

Visitor emails are captured inside the widget and listed under Leads with the conversation they came from — exportable to CSV and webhook-able for CRM sync.

Notifications

Per-site OneSignal configuration (kept private — never exposed in the public widget config) delivers browser push on new leads and handoff requests. Email notifications cover the same events.

Team & agents

Invite agents and assign them to sites. Agents see only their assigned sites' conversations and handoffs; account owners keep full control.

Platform & users

Master admins manage every account under Platform: create/edit users, set plans, suspend accounts, and delete users with the choice to transfer their sites and agents to the master account or remove everything. The same section configures landing-page content (ad slots, demo site, booking embed).

Plans & billing

Basic (€10/mo) — widget, crawler, lead capture, standard AI engine, core analytics.
Advanced (€25/mo) — adds white-label, Help Center portal + custom domain, video knowledge, human handoff and priority support.

Yearly billing saves ~17%. VAT applies at the legal rate. Stripe price IDs are configured through environment variables.

PWA & install

The dashboard and landing are installable Progressive Web Apps (manifest + service worker). Serve over HTTPS and use the browser's Add to Home Screen — bottom-nav mobile layout included.

Deployment

Docker-first: the Dockerfile produces a single all-in-one image (backend + frontend + crawler + headless browser). Required environment:

MONGODB_URL=mongodb://mongo:27017
MONGODB_DB=sitechat
JWT_SECRET=<random 32+ chars>
SITE_URL=https://your-host
MASTER_ADMIN_EMAIL=you@company.com
CRAWLER_JS_RENDER=true

docker-compose.yml adds MongoDB and optional Ollama; on Coolify deploy via the Dockerfile plus a separate MongoDB resource with MONGODB_URL pointing at it.

Missing something? The Help Center at /hc has bite-sized versions of these guides for your own visitors — and the in-widget Help tab serves the same articles during chats.