xchats

xchats

The self-hosted omnichannel inbox with zero-hallucination AI. WhatsApp and Telegram in one shared inbox — an AI assistant drafts every reply from your own knowledge base, and a human approves it before it sends. Customer profiles, follow-ups and campaigns included; Instagram, Messenger and WhatsApp Cloud API are coming soon.

English · Русский · Қазақша

---

60-second quickstart

git clone https://github.com/yerassyldanay/xchats.git
cd xchats
make up
make seed

Open http://localhost:8081 — sign in with admin@xchat.kz / xchat-admin-change-me (public default; change it after your first login). make seed fills the local instance with the Qazan Home kitchen-appliance demo and is safe to run again.

Key superpowers

• Zero-hallucination replies — the model never writes a price, date or contact detail itself. It emits a {{token}}; the backend substitutes the exact stored value, or the draft fails closed and escalates to a human.
• Human-in-the-loop, always — every draft is a suggestion. Nothing reaches a customer until a teammate clicks Send.
• Choose SQLite or PostgreSQL — Go + embedded SQLite by default, with PostgreSQL available through storage.database_target. See Database architecture and migrations. No Redis, no managed cloud service required to run this.
• Model-agnostic — OpenAI, Claude, Gemini, OpenRouter or a local Ollama model; swap providers from Settings, not code.
• Configurable from ChatGPT / Claude — an MCP connector lets an LLM client read your documents and stage knowledge-base edits for your review.

Visual tour

These are real screens from a seeded Qazan Home instance, not mockups. They are regenerated from the running app by make screenshots.

1. Sign-in and first steps

The sign-in page says what xchats is and what it does. After signing in, the Dashboard shows what needs attention (unread chats, overdue follow-ups, changes waiting in the Draft) and, for a new workspace, a "Getting started" checklist; the setup wizard walks an admin through the AI key, a first channel and the knowledge base.

2. Shared inbox

WhatsApp and Telegram conversations share one queue. AI replies remain suggestions until a teammate edits, approves or discards them; the customer panel keeps the profile, status, tags, next step and notes beside the chat.

3. Channels and automation

Connect WhatsApp by QR code or a Telegram bot. Every account is a card with its own channel icon, health, an AI-suggestions switch and a schedule for auto-reply (always, nights, weekends or custom hours). Instagram, Messenger and WhatsApp Cloud API are implemented in the backend but switched off in the UI for now ("Coming soon"); build the frontend with VITE_ENABLE_META_CHANNELS=true to bring them back.

4. Grounded knowledge base

Products, tariffs, delivery zones, contacts and policies are the only facts the assistant may use, together with its persona and guardrails. Numbers become {{token}} placeholders and are filled from stored values; see the grounding pipeline.

5. Draft: review and ChatGPT / Claude

The Draft page has the same anatomy as the Knowledge Base. Links, files and the MCP connector all write to it; ChatGPT or Claude can use 13 kb_* tools after OAuth 2.1 authorization, but every change shows up as a before/after card and still needs human review before publishing.

6. Test the assistant

Rehearse customer questions against the live Knowledge Base or the Draft — no real phone number needed — or ask the private operator assistant about live facts and pending changes. Neither ever messages a customer. Compare prompts and models with the open evals/ harness.

7. Customers and follow-ups

The mini CRM keeps identities, notes, tags and ownership together; its daily board tracks overdue, upcoming and completed follow-ups.

8. Campaigns

A three-step wizard — audience, message, schedule — imports recipients, previews templates and sets rate limits and send windows; then every delivery and reply is tracked in the shared inbox.

9. Settings and team

Configure model providers, extraction, Langfuse monitoring, remote access, channels, team access and backups from the UI — no secrets belong in config.yaml.

How it works

1. A customer messages you on WhatsApp or Telegram.
2. It lands in one inbox, shared by your whole team.
3. The assistant drafts a reply from your approved knowledge base only.
4. A person reviews, edits or discards it — then sends.

The full design lives in docs/overview.md; the grounding mechanism is summarized in the visual tour.

Run it another way

• From source (dev): make dev-backend + make dev-frontend — see docs/release/installation.md.
• Desktop app (Wails — Windows/macOS/Linux): make desktop-build — see docs/desktop.md.
• make help lists every target.

[!WARNING] The WhatsApp channel connects like WhatsApp Web (no Business API fee), but it is an unofficial client — start with a number you can afford to lose. Details in the visual tour.

Documentation

• docs/overview.md — product and architectural overview
• docs/release/installation.md — every install path
• docs/desktop.md — the desktop app
• CONTRIBUTING.md — dev setup, conventions, PRs
• SECURITY.md — reporting a vulnerability

License

AGPL-3.0-only — chosen after a GPL-3.0 dependency (pulled in transitively through the WhatsApp integration) was found statically linked into the backend; see THIRD_PARTY_NOTICES.md.