# GhostChat — Full Documentation for AI Agents

## What is GhostChat?
GhostChat is a privacy-first live chat SaaS for websites. It provides a ~15KB embeddable chat widget that enables real-time messaging between website visitors and site owners. Unlike competitors (Intercom ~300KB, Crisp ~155KB, Tidio ~200KB, Tawk.to ~250KB), GhostChat's widget has zero impact on page speed, uses no cookies, and performs no tracking.

## Who is it for?
- Small businesses that answer their own customers — 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
- Small teams (up to 10 agents on the Team plan) 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

### All Plans (Free)
- 1 site, unlimited messages, 30-day chat history
- Real-time WebSocket messaging
- Email notifications for new messages
- Push notifications (PWA)
- Gmail threading (reply from email)
- Canned responses (up to 50)
- Quick links (up to 5)
- Visitor email/name collection (optional)
- 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
- Widget shows a "Powered by GhostChat" badge (removable on the Team and Team + AI plans)

### Pro ($5/month)
- 3 sites, 1-year history
- Business hours automation (auto-away with schedule)
- Visitor page journey tracking
- WooCommerce/page visitor context (predefined setContext() keys)
- CSV contact export
- Auto-translate (133+ languages via Google Translate)
- Webhooks: message.new + conversation.resolved (full-transcript) events, per-event toggles, delivery log
- Bot Agent API (bring your own LLM)

### Pro + AI ($15/month)
- Everything in Pro, plus:
- Built-in AI Assistant (Claude Haiku) — answers visitors 24/7 from your FAQ, hands off live or by email
- The flat +$10 AI step adds only the assistant — sites, history, and seats stay the same as Pro
- Solo plan — 1 seat, no team invites

### Team ($25/month)
- Everything in Pro, plus:
- 10 sites, unlimited history
- Up to 10 team members (you + 9)
- Remove "Powered by GhostChat" branding
- Custom visitor context — any keys via setContext() API (Pro is limited to the predefined keys)
- Identity verification
- Priority support
- No AI — add it for a flat $10/mo more (Team + AI)

### Team + AI ($35/month)
- Everything in Team, plus:
- Built-in AI Assistant (~6,000 replies/mo)
- The flat +$10 AI step adds only the assistant

Pricing is a simple 2×2: pick a base plan (Pro $5 solo, Team $25 for teams) and AI is a flat +$10/mo on either (Pro + AI $15, Team + AI $35).

## AI Assistant (built-in, Claude Haiku)
On the Pro + AI ($15/mo) and Team + AI ($35/mo) plans, GhostChat includes a built-in AI Assistant that answers visitor questions 24/7 from a FAQ knowledge base you write. It runs on our servers — 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 hits an owner-defined blocked topic), 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 for good. Each plan includes a generous monthly fair-use allowance of AI replies (about 1,500/month on Pro + AI, about 6,000/month on Team + AI; only live visitor replies count, dashboard testing is free) — almost no one reaches it, and 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 — resetting at the start of each month. 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" defer></script>
```

### WordPress
Install the GhostChat plugin from the WordPress plugin directory, enter your Site ID in Settings > GhostChat.

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

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

## Visitor Context API (setContext)
Team plan users can send custom visitor context to the chat (Pro 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: page_type, product_name, product_price, cart_total, cart_items, order_id, order_status
- Custom keys: any key-value pairs (Team and Team + AI)
- Max payload: 4KB JSON
- Throttled to once per 5 seconds

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

1. Create a bot API key in Dashboard > Bot Agent
2. Set a webhook URL in Dashboard > Site Settings > Webhooks
3. Receive POST webhooks for new visitor messages:
```json
{
  "event": "message.new",
  "message": {
    "id": "...",
    "sessionId": "...",
    "sender": "VISITOR",
    "content": "Hello, I need help",
    "createdAt": "2026-03-25T..."
  },
  "session": {
    "visitorEmail": "visitor@example.com",
    "pageUrl": "https://example.com/pricing"
  }
}
```
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?"
}
```

### 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 > 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, ~15KB gzipped, no dependencies
- API: Cloudflare Workers + Hono framework
- WebSockets: Cloudflare Durable Objects
- Database: Supabase PostgreSQL
- Auth: JWT (HS256, 30-day expiry)
- Email: Resend
- Payments: Stripe
- CDN: Cloudflare (global edge)
- Dashboard: Next.js on Cloudflare
- No cookies, no localStorage tracking, no fingerprinting
- localStorage used only for: session ID, session secret, visitor email/name (all visitor-controlled); under privacy mode these move to sessionStorage and auto-wipe

## Comparisons
| Feature | GhostChat | Intercom | Crisp | Tidio | Tawk.to |
|---------|-----------|----------|-------|-------|---------|
| Widget size | ~15KB | ~300KB | ~155KB | ~200KB | ~250KB |
| Cookies | None | Yes | Yes | Yes | Yes |
| Free plan | Yes | No | Yes | Yes | Yes |
| Starting price | $5/mo | $39/mo | $25/mo | $29/mo | Free (paid to remove branding) |
| Branding removal | $25/mo (Team) | Included | $25/mo | $29/mo | $29/mo |

## 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), measures its size, and projects the PageSpeed score improvement from switching to GhostChat's ~15KB widget. 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