# GhostChat — Full Documentation for AI Agents

## What is GhostChat?
GhostChat is a privacy-first live chat SaaS for websites. It provides a lightweight embeddable chat widget that enables real-time messaging between website visitors and site owners. In our measured August 2026 benchmark (https://ghostchat.dev/blog/chat-widget-lighthouse-benchmark), GhostChat transfers 18.9KB total including opening the chat panel, versus Intercom 1,104KB (271KB on load + 833KB when opened), Tawk.to 462KB, Crisp 267KB (127KB + 140KB on open), and LiveChat 44KB. GhostChat's widget adds ~10ms of CPU over an empty page, uses no cookies, and performs no tracking.

## Who is it for?
- Small businesses that answer their own customers — shops, schools, nonprofits, consultants, small SaaS — nobody's full-time job is watching chat
- Anyone running several sites who doesn't want a separate subscription for each one
- Privacy-conscious businesses that want GDPR compliance without cookie banners
- Teams of up to 10 people (Team, one flat price) that don't want per-seat pricing
- Agencies managing client sites from a single login
- Developers who want to connect their own LLM via the Bot Agent webhook API

## Features

### Free ($0)
- 1 site, 1 seat, unlimited messages, 30-day chat history
- Real-time WebSocket messaging
- Email notifications for new messages
- Push notifications (Android app on Google Play, or the PWA on iOS and desktop)
- Gmail threading (reply from email)
- Canned responses (up to 50)
- Quick links (up to 5)
- Visitor email/name collection (optional while Online; asked for before writing whenever the widget is Away)
- Automatic Away whenever nobody has the dashboard open, so visitors leave their email
- Archive/unarchive conversations
- Contact management
- Privacy mode (per-site toggle): visitor-side chat lives in sessionStorage only and wipes after 15 minutes of inactivity — built for shared or monitored computers; the dashboard keeps every conversation
- No AI Assistant (the assistant is an option on the paid plans, billed per AI conversation)
- Widget shows a "Powered by GhostChat" badge (removable on Team and up)

### Starter ($5/month)
- Everything in Free, plus:
- 1-year chat history
- Business hours automation (stay Online on a schedule, dashboard open or not; Away outside it with a "back at" time) — so you never miss a lead
- Visitor page journey tracking
- WooCommerce/page visitor context (predefined setContext() keys)
- CSV contact export
- 3 sites, still 1 seat
- Webhooks: message.new + conversation.resolved (full-transcript) events, per-event toggles, delivery log
- Bot Agent API (bring your own LLM)
- Your own logo on the chat button and in the widget header (per site)
- AI Assistant optional: $0.10 per AI conversation, knowledge base of 25 Q&As per site. No auto-translate
- Widget still shows a "Powered by GhostChat" badge

### Team ($25/month)
- Everything in Starter, plus:
- Up to 10 team members (you + 9), one shared inbox, never per seat
- Unlimited sites, unlimited history
- Chat assignment: give a chat to one teammate; a "Mine" filter shows only yours
- See when a teammate is already replying, so two people don't answer the same chat
- Roles: Admins run the account with you; Agents answer chats and can restyle the widget, but can't touch billing, the team, or a site's domain and data settings
- Team stats: chats and first-reply time per person
- Your logo, name and colours, with no "Powered by GhostChat" badge in the chat and no GhostChat footer in emails to visitors
- Auto-translate (133+ languages via Google Translate)
- Custom visitor context — any keys via setContext() API (Free and Starter are limited to the predefined keys)
- Identity verification
- Guided setup & priority support — we help you get it installed and wired into your stack
- AI Assistant optional: $0.10 per AI conversation, knowledge base of 50 Q&As per site

### AI assistant (optional on Starter or Team, billed per AI conversation)
- Switched on in the dashboard on either paid plan; it is an option, not a separate plan, and there are no credit packs
- $0.10 per AI conversation, added to the subscription's invoice. You pay $0.10 once the AI gives a real answer. If it hands off before answering anything, it's free.
- One conversation counts once, never per message, even if the team takes it over later; a visitor back after 24 hours of silence starts a new one
- A spending limit per billing period, set by the owner ($20 by default, or none). You set the limit. We never charge a cent over it. Lowering it doesn't refund chats the AI already answered. At the limit the chat keeps working and hands off to a human; the limit resets when the subscription renews
- Never billed: the canned reply to a bare greeting or junk message that opens a chat; chats on any domain but the site's own (the AI doesn't answer there); a visitor's 4th and later AI conversation of the day on one site, and visitors on many VPNs, corporate virtual desktops and cloud networks unless the owner allows them (those chats go to a human or the email form instead)
- Setup and testing in the dashboard are free (5 Generate-with-AI runs and 50 test replies a month)
- Coupons don't apply to AI charges; a billing period's last day or two can appear, dated, on the following invoice
- Switching it off does not cancel conversations it already answered. Available on Stripe-billed subscriptions; not through Shopify billing

### Custom
- More than 10 seats, integrations built to spec, multi-site rollouts — talk to us. No published price.

Pricing is three flat plans — Free $0, Starter $5/month, Team $25/month. Seats: Free 1, Starter 1, Team 10; Team also removes the branding. No per-seat fees. Billing is monthly only — there is no annual plan (ask if you want to pay a year up front) — and there is no free trial: the Free plan is free forever. Human conversations are unlimited on every plan. The one thing billed by use is the optional AI assistant: on Starter or Team it costs $0.10 per AI conversation, added to the subscription's invoice. You pay $0.10 once the AI gives a real answer. If it hands off before answering anything, it's free. A conversation counts once even if the team takes it over later; a visitor back after 24 hours of silence starts a new one. The owner sets a spending limit per billing period ($20 by default, or none): You set the limit. We never charge a cent over it. Lowering it doesn't refund chats the AI already answered. At the limit the chat keeps working — visitors reach a human live or leave their email — and the limit resets when the subscription renews. The knowledge base, 50 free dashboard test replies a month and 5 free Generate-with-AI runs a month come with the switch. The assistant is an option on the paid plans, not a separate plan.

## AI Assistant (built-in, Claude Haiku)
On Starter or Team, switched on in the dashboard at $0.10 per AI conversation, GhostChat includes a built-in AI Assistant that answers visitor questions 24/7 from a FAQ knowledge base you write. We run it for you — no API key or extra infrastructure. Setup is one click: press "Generate with AI" and GhostChat crawls your own website (up to a handful of pages) and uses Claude to draft your bot name, behavior instructions, blocked keywords, and a starter set of FAQ question-and-answer pairs, which you review, edit, and apply — so you never start from a blank knowledge base. When it can't answer (or a message contains a word or phrase the owner has blocked), it hands off: if you're available it offers to connect the visitor with you live and captures their email as a backup; if you're away it captures their name and email so you can follow up. You take over any conversation simply by replying, and the AI steps aside; if the visitor comes back after 24 hours of silence, the AI answers again and that counts as a new conversation. You pay $0.10 once the AI gives a real answer. If it hands off before answering anything, it's free. The owner sets a spending limit per billing period ($20 by default, or none). You set the limit. We never charge a cent over it. Lowering it doesn't refund chats the AI already answered. At the limit the chat still works: visitors reach you live when you're available, or leave their email when you're away, instead of getting an AI-drafted reply; the limit resets when the subscription renews. Configure it from the "Who answers your chats?" selector on the /ai dashboard page.

## Installation

### Basic (any website)
```html
<script src="https://api.ghostchat.dev/widget.js" data-site="YOUR_SITE_ID" data-no-optimize="1" defer></script>
```
Not the one who edits your site? While the widget isn't installed yet, the dashboard's Install card has "Email them the steps": it opens a ready-made email in your own mail app (or copies the message) to send to whoever runs your site.

### WordPress
Install the GhostChat plugin from the WordPress plugin directory, enter your Site ID in Settings > GhostChat.
The plugin (1.4.0+) also controls where the chat appears: on every page, only on pages you choose, or built into a page. For the last option, paste the [ghostchat_embed] shortcode into that page — optionally sized with [ghostchat_embed width="400" height="600"] — and the chat renders as an inline panel there instead of a floating bubble.

### React / Next.js
```jsx
<script src="https://api.ghostchat.dev/widget.js" data-site="YOUR_SITE_ID" data-no-optimize="1" defer></script>
```
Or use useEffect to load dynamically.

### Shopify
Add the script tag to your theme.liquid file before </body>.

### Webflow
Site settings > Custom code > Footer code: paste the script tag, save, then publish. Custom code only runs on the published site, and Webflow allows it only with a paid Site plan or a paid Workspace. Guide: https://ghostchat.dev/chat-widget-for-webflow

### Bubble
Install the GhostChat Live Chat plugin from the Bubble marketplace, then open the Plugins tab and paste your Site ID. The chat appears on every page, with no element or workflow to add. Plugin: https://bubble.io/plugin/ghostchat-live-chat-1791892224282x583996372266778600

## Visitor Context API (setContext)
Team plan users can send custom visitor context to the chat (Starter and up can send the predefined WooCommerce/page keys):
```javascript
window.GhostChat.setContext({
  page_type: 'product',
  product_name: 'Blue Widget',
  cart_total: '$49.99',
  custom_field: 'any value'
});
```
- Predefined keys (stored on every plan): page_type, product_name, cart_items, cart_total, cart_count
- Free stores all five but only DISPLAYS page_type and product_name; the three cart keys are withheld and shown as a locked count. Starter and up see all five.
- Custom keys: any other key-value pairs — Team only. On Free and Starter they are rejected with HTTP 403 and code PLAN_UPGRADE_REQUIRED, listing the dropped keys. The widget sends context fire-and-forget and does not read the response, so this rejection is visible in the browser Network tab, not the console.
- Max 20 keys per session
- Max payload: 4KB JSON per setContext() call (the merged total per session is not capped)
- Throttled to once per 5 seconds

## Widget JavaScript API
Available on all plans once the widget script loads:
- window.GhostChat.open() / .close() / .toggle() — control the widget
- window.GhostChat.on(event, callback) — events: open, close, message
- window.GhostChat.setContext(data) — see Visitor Context API above
- window.GhostChat.reset() — programmatic "Clear chat from this device": archives the current conversation to the dashboard and wipes all local history, identity, and context so the next person on the device starts a completely fresh conversation. Returns a promise. Built for shared devices and kiosks (e.g. call it when a support interaction ends).

## Kiosk & Shared Devices recipe
For one browser/machine shared by many people (support desks, kiosks, in-store terminals), the whole pattern is two calls:
```javascript
// 1 — Your pre-chat form hands the details to the widget, then opens the chat.
//     setContext() is synchronous.
function startSupportSession({ name, email, phone, reason }) {
  GhostChat.setContext({ name, email, phone, reason });
  GhostChat.open();
}
// 2 — Interaction over. Archives the conversation to your dashboard, then wipes
//     every trace from the device: messages, name, email, session secret,
//     custom context, and page journey.
async function endSupportSession() {
  await GhostChat.reset();
}
// Safe to call when nobody chatted — with no conversation to archive it just clears the device.
```
- setContext({ name }) seeds the conversation's display name in the dashboard inbox — no identity verification needed. It fills only a blank name and never overwrites one the visitor typed.
- reset() works on every plan. Only the custom context keys in the example (name, email, phone, reason) require the Team plan — on Free and Starter they're rejected (see Visitor Context API above).
- reset() vs. the privacy-mode idle wipe: privacy mode's 15-minute idle timeout wipes the device but does NOT archive the conversation — it stays open in the dashboard. reset() does both. Treat the idle wipe as a backstop, not the primary mechanism.
- Resolving a conversation in the dashboard does not clear the kiosk device — only reset() (or the visitor's "Clear chat from this device") does.
Full guide: https://ghostchat.dev/developers#kiosk

## Bot Agent API (Webhooks)
Available on every paid plan (Starter and up), automate responses with your own AI (Bot Agent / BYOA):

1. On the AI page in the dashboard, choose My own AI and generate a gc_bot_ API key
2. On the same page, set your bot's endpoint (the HTTPS URL your bot listens on). GhostChat POSTs each new visitor message there while the built-in AI is off for that site — once, with no retries; deliveries are logged in Settings → Developer → Deliveries
3. The payload (message.new); imageUrl, visitorEmail, pageUrl, referrer and country are left out when unknown:
```json
{
  "event": "message.new",
  "siteId": "...",
  "siteName": "My Store",
  "sessionId": "...",
  "messageId": "...",
  "content": "Hello, I need help",
  "imageUrl": "https://...",
  "visitorEmail": "visitor@example.com",
  "pageUrl": "https://example.com/pricing",
  "referrer": "https://example.com/",
  "country": "US",
  "createdAt": "2026-03-25T..."
}
```
4. Reply via API:
```
POST https://api.ghostchat.dev/messages/owner
Authorization: Bearer gc_bot_YOUR_API_KEY
Content-Type: application/json

{
  "sessionId": "SESSION_ID",
  "content": "Hi! How can I help?"
}
```
A bot key can only reply (POST /messages/owner) and configure the widget (PUT /sites/:siteId with color, position, icon, welcomeMessage, awayMessage or botWebhookUrl). It cannot list sites or read conversations.

Quick start: `npx ghostchat-agent --setup` in an empty folder asks for your key and site ID, writes a starter knowledge base (ghostchat.md), opens a Cloudflare tunnel to your machine and saves it as your bot endpoint; `node index.js` then runs the bot with Ollama, OpenAI or Anthropic.

The site webhook (Dashboard > Site Settings > Webhooks) is separate: it is for notifications such as Slack or a CRM, fires in every mode, and carries message.new and conversation.resolved.

### conversation.resolved (full-transcript webhook)
When a conversation is resolved — manually, via bulk action, or by the daily auto-archive sweep — GhostChat POSTs one complete snapshot to your webhook URL. Key it on the stable conversationId and upsert: re-resolves re-send the same ID with the fuller transcript (latest wins). The payload carries visitor fields as hints (browser-scoped id, name/email when present), the full pageJourney, and a messages array with role (visitor/agent), ISO 8601 timestamps with offset, text, and attachments as {url, name} — attachment URLs fetch without auth. Conversations with zero messages never fire. Per-event toggles (message.new / conversation.resolved) sit next to the webhook URL in site settings, and every delivery attempt is visible with its status code in Dashboard > Settings > Developer > Deliveries.

## Widget Customization
Configured via the dashboard (Site Settings):
- Brand color (hex)
- Position (bottom-right or bottom-left)
- Icon (chat, headset, help, message, support, wave)
- Welcome message
- Away message
- Quick links (up to 5 labeled URLs)

## Technical Details
- Widget: Vanilla JavaScript IIFE, no dependencies; 18.9KB total transfer including opening the chat (measured Aug 2026)
- API: Cloudflare Workers + Hono framework
- WebSockets: Cloudflare Durable Objects
- Database: Supabase PostgreSQL
- Auth: JWT (HS256, 30-day expiry)
- Email: Resend
- Payments: Stripe
- Widget/API CDN: Cloudflare (global edge)
- Dashboard: Next.js on Vercel
- No cookies, no third-party tracking, no fingerprinting
- Browser storage (localStorage, never cookies; nothing is written until the visitor opens the chat): session ID, session secret, and the visitor-provided email and name. Pages viewed on the site before the chat is first opened are held in the page's memory only (up to 50; sent once when the chat is opened, then cleared; not kept in privacy mode). Under privacy mode the chat lives in sessionStorage with a heartbeat timestamp and is wiped when the tab closes or after 15 minutes of inactivity

## Comparisons
| Feature | GhostChat | Intercom | Crisp | Tidio | Tawk.to |
|---------|-----------|----------|-------|-------|---------|
| Widget size (measured Aug 2026, incl. opening the chat) | 18.9KB | 1,104KB | 267KB | not verifiable (508KB downloaded, widget never rendered in our test) | 462KB |
| Cookies | None | Yes | Yes | Yes | Yes |
| Free plan | Yes | No | Yes | Yes | Yes |
| Starting price | $5/mo (Starter); AI $0.10 per conversation on top | $39/mo | $45/mo | $29/mo | Free (paid to remove branding) |
| Branding removal | $25/mo (Team) | Included | $295/mo (Plus) | $79/mo (Growth + add-on) | $29/mo per site |
| AI assistant pricing | $0.10 per AI conversation on either paid plan, free when it hands off before answering, under a spending limit the owner sets | Fin: $0.99 per outcome | Credit packs (≈$0.05–0.10 per AI conversation); AI stops when credits run out | Lyro, metered, from $39/mo | from $29/mo per site |

Beyond this table: Chatway meters AI at $0.50 per resolved conversation (10 free one-time); Chatwoot prices per agent ($19–99/agent/mo with no billing period stated; branding removal Enterprise-only) with AI credits at 1 per message. GhostChat's AI is cheaper per conversation than Intercom Fin ($0.99 per outcome), Chatway ($0.50 per resolution) and Tidio Lyro ($0.78 per conversation at its entry tier), charges nothing when the AI hands off before answering, and comes with a spending limit the owner sets. (Competitor figures read from vendor pricing pages, October 6 2026.)

All five vendors in one table — weight, AI billing model, ten-person cost and when to pick each instead: https://ghostchat.dev/compare

Detailed side-by-side pages, each with the measured numbers above plus feature tables and FAQs:
- vs Tawk.to: https://ghostchat.dev/tawk-to-alternative
- vs Crisp: https://ghostchat.dev/crisp-alternative
- vs Chatwoot: https://ghostchat.dev/chatwoot-alternative
- vs Chatway: https://ghostchat.dev/chatway-alternative
- vs Intercom: https://ghostchat.dev/intercom-alternative
- vs HelpCrunch: https://ghostchat.dev/helpcrunch-alternative (per-seat pricing and features; HelpCrunch is not in the measured benchmark)

## Free Tools
- Website Speed Test (https://ghostchat.dev/website-speed-test): A free interactive tool. Enter any URL and it runs a real Google Lighthouse audit (via the PageSpeed Insights API), detects the chat widget currently installed (Intercom, Drift, Zendesk, Crisp, Tawk.to, Tidio, HubSpot, LiveChat), and reports the widget's transfer cost using our own August 2026 measurements — including what it downloads when a visitor opens the chat. It deliberately does not predict a PageSpeed score, because Lighthouse scores barely differ between chat widgets (and Crisp's widget declines to load during Lighthouse audits, so scores on Crisp sites are flattering). Results are shareable via link/email/WhatsApp. No signup required.

## URLs
- Website: https://ghostchat.dev
- Website Speed Test: https://ghostchat.dev/website-speed-test
- Dashboard: https://app.ghostchat.dev
- API: https://api.ghostchat.dev
- Pricing: https://ghostchat.dev/pricing
- Features: https://ghostchat.dev/features
- Developers: https://ghostchat.dev/developers
- Bot Agent: https://ghostchat.dev/bot-agent
- Get Started: https://ghostchat.dev/get-started
- FAQ: https://ghostchat.dev/faq
- GDPR: https://ghostchat.dev/gdpr-chat-widget
- Blog: https://ghostchat.dev/blog
- Privacy Policy: https://ghostchat.dev/privacy
- Terms: https://ghostchat.dev/terms