Documentation

Everything you need to run CoilChat.

A practical guide to the platform — from dropping in the widget to closing the learning loop. New here? Start with the getting-started guide.

Overview

CoilChat is an AI-first customer-support desk with human handoff. The AI answers questions grounded in your knowledge; when it isn't confident — or a visitor asks for a person — the chat escalates to your team, who reply live in the same widget. Every chat your team resolves is distilled into reusable knowledge, so the assistant keeps getting sharper.

There are three surfaces:

  • The widget — the embeddable chat box your customers use.
  • The dashboard at app.coilchat.com — where you configure the AI, manage knowledge, and where your team handles live chats from the Inbox.
  • The learning loop — the background pipeline that turns resolved chats into knowledge.

Quickstart

  1. Create a workspace at app.coilchat.com.
  2. Add a knowledge source under Sources (crawl your site, upload docs, or connect a database).
  3. Copy your snippet from Install and paste it on your site.
  4. Invite teammates on Team and have them go online in the Inbox.

That's a working desk. The full walkthrough lives in the getting-started guide.

The widget

Add one script tag before </body> on any page:

<script src="https://app.coilchat.com/widget.js" data-api-key="pk_live_your_key"></script>

The pk_live_ key is a publishable key — it's meant to ship in your page's HTML, like an analytics ID. Abuse is bounded by a per-IP rate limit and an optional domain allowlist, not by secrecy.

Customize it

Under Settings → Widget: theme (light or dark), position, size & text scale, launcher label, logo, starter chips, a pre-chat form, and your privacy-policy link. Changes apply within the widget's short cache.

Restrict it

On the Install page, add a domain allowlist so the key only works on your sites, and rotate the key any time.

Knowledge sources

Sources feed the AI. Add them on the Sources page:

  • Website crawl — enter one or many URLs (one per line, up to 100), or a single URL with a crawl depth. Depth controls how many link-hops to follow: 0 = just the page(s) you give it, 1 = those plus the pages they link to, 2 = two hops. A single URL also auto-discovers your sitemap.xml.
  • Upload — PDFs (text-extracted server-side), plain text, or Markdown.
  • Database — sync problem/resolution pairs from Supabase or Postgres.

Everything is cleaned (boilerplate stripped), split into heading-aware chunks, and embedded for retrieval. Documents are never summarized — the AI retrieves your actual wording so it can answer faithfully and cite sources.

Re-sync & reset

Re-sync re-fetches and re-embeds a source in place. Reset & retrain (workspace-wide) wipes all embeddings and rebuilds every source from origin. Deleting a source removes its documents, chunks, and resolutions completely.

A source shows pending for the whole duration of a crawl — it flips to done only when the entire crawl finishes and stores its pages.

AI behaviour

Shape how the assistant answers under Settings — no code required:

  • Custom instructions — persona, tone, rules, and things it should never say.
  • Grounding strictness — how strong a knowledge match it needs before answering a specific question. Higher means it escalates sooner rather than guessing.
  • Inactivity follow-ups — if a visitor goes quiet, the AI nudges ("still there?") and then closes the chat gracefully, on your timing.
  • AI fallback — if an escalated chat sits unclaimed past a set time (e.g. after hours), the AI takes back over and keeps helping, so no one is stranded.
  • Model — pick your provider/model under Settings → Model.

By design, the AI answers greetings and small talk naturally, uses your knowledge for support questions, and refuses to invent business-specific facts (prices, policies, account details) it can't ground.

Human handoff & the Inbox

When the AI escalates — low confidence, or a direct request for a person — the chat moves to a department queue. Online agents see it in the Inbox, claim it, and reply live in the visitor's widget. They can also jump into a live AI chat at any time.

From a chat an agent can Draft with AI (a grounded suggested reply), leave internal notes and @mention teammates, assign it, send images and voice, then Resolve (which feeds the learning loop) or Release back to the AI.

The learning loop

When an agent resolves a chat, CoilChat distills that conversation into a generalized {problem, resolution} pair using an LLM — not a verbatim copy. By default it lands as pending on the Learned page for review, so nothing enters the AI's knowledge without a human approving it. Approve it, and the next time that question comes up, the AI handles it automatically. You can Unlearn any lesson at any time.

Documents vs. lessons. Crawled/uploaded content is chunked and embedded verbatim. Distillation only applies to the chat-learning loop — conversations get generalized; documents don't.

Saved replies (slash key)

Build a shared library of canned replies on the Shortcuts page. In the Inbox composer, type / followed by a keyword to insert one instantly — arrow keys to pick, Enter to insert.

Team & roles

Invite teammates on the Team page. Roles:

  • Owner — full control, including billing and other owners.
  • Admin — manage settings, sources, keys, and teammates (can't grant the owner role).
  • Agent — handle chats from the Inbox; no access to workspace settings or keys.

Group agents into departments so escalations route to the right people. Presence (online/away/offline) drives who can claim a queue.

Security

  • Tenant isolation — every workspace's data is isolated at the database row level; one workspace can never read another's.
  • Encryption — connector credentials are encrypted at rest with AES-256-GCM and never returned by the API or logged. Traffic is TLS-encrypted end to end.
  • Access control — role-gated admin actions, CSRF protection, signed session cookies, and optional per-user two-factor authentication.
  • Safe by default — uploads are validated by content (not filename) and served inert; outbound connectors are guarded against SSRF; the learning loop never goes live without approval.

Questions about security or data handling? Get in touch — and see our Privacy Policy.

FAQ

Will the AI make things up?

It's built not to. Answers are grounded in your knowledge, and a confidence gate makes it escalate rather than fabricate business-specific facts.

What happens after hours?

If no agent is online, escalated chats wait in the queue, the visitor can leave an email, and — if you enable AI fallback — the assistant takes back over so they still get help.

Can I export or delete my data?

Yes. You control your sources and learned knowledge, and you can delete a source (removing its content entirely) or reset your knowledge base at any time. For account-level export or deletion, contact us.

Does the widget slow down my site?

No — it's a single small script that loads asynchronously and renders its own UI without touching your page's layout.