```
➡️ **[AI Agent & Automation Quickstart](https://docs.chattermate.chat/features/agents-quickstart)** · **[CLI reference](https://docs.chattermate.chat/features/cli)** · **[MCP server](https://docs.chattermate.chat/features/mcp-server)**
> 🤖 **Building an AI agent that sets up ChatterMate?** Start at
> [`chattermate.chat/llms.txt`](https://chattermate.chat/llms.txt), follow the
> [agent quickstart](https://docs.chattermate.chat/features/agents-quickstart), or connect the
> [MCP server](https://docs.chattermate.chat/features/mcp-server) to configure ChatterMate over MCP.
### Option B — Self-host with Docker
Run the full ChatterMate stack on your own infrastructure with the **self-host CLI** (Docker-based):
```bash
# Install the self-host / deployment CLI
npm install -g chattermate-deploy
# Scaffold a project, then start the full stack (Postgres, Redis, backend, frontend, worker)
chattermate-deploy init my-chattermate-project
cd my-chattermate-project
chattermate-deploy start # then open http://localhost/
```
Self-host CLI commands
```bash
chattermate-deploy init # Scaffold a new self-hosted project
chattermate-deploy start # Start all services (Docker)
chattermate-deploy stop # Stop all services
chattermate-deploy status # Check service status
chattermate-deploy logs # View service logs
chattermate-deploy reset # Reset and remove all data
```
> ⚠️ **Two different `chattermate` commands — don't mix them up.** The **hosted CLI**
> (`pip install chattermate-cli`) signs you up and manages agents/knowledge against the
> ChatterMate API. The **self-host CLI** (`npm install -g chattermate-deploy`) scaffolds and runs
> the Docker stack. They are separate tools that happen to share the `chattermate` name.
---
## Installation Methods
> Prefer the hosted service? Skip this section — just [sign up](https://app.chattermate.chat)
> and/or use the [ChatterMate CLI](https://docs.chattermate.chat/features/cli)
> (`pip install chattermate-cli`). The methods below are for **self-hosting**.
### Prerequisites
**For Self-Host CLI (Recommended)**
- Node.js 16+
- Docker & Docker Compose
- npm or yarn
**For Manual Installation**
- Python 3.12+
- PostgreSQL 14+ (with Vector extension)
- Firebase Project (for push notifications)
- Redis (optional, for rate limiting and multi-server socket deployment)
### Method 1: Self-Host CLI (Recommended)
The self-host CLI (`chattermate-deploy`, installed via npm) scaffolds and runs the Docker stack.
This is **not** the account CLI — for signup and agent management see the
[ChatterMate CLI](https://docs.chattermate.chat/features/cli).
```bash
npm install -g chattermate-deploy
chattermate-deploy init my-project
cd my-project
chattermate-deploy start
```
### Method 2: Docker Installation
```bash
# Build and start all services
docker compose up --build
# Run in background
docker compose up -d
# Stop services
docker compose down
# View logs
docker compose logs -f
```
### Method 3: Manual Installation
Click to expand manual installation steps
#### Backend Setup
```bash
cd backend
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
# Set up environment variables
cp .env.example .env
# Configure .env with your credentials
# Database setup
alembic upgrade head
# To generate revisions if any model changes
alembic revision --autogenerate -m "Changes description"
```
#### Frontend Setup
```bash
cd frontend
npm install
cp .env.example .env
```
For Web Push notification, generate a firebase config and place it in `backend/app/config/firebase-config.json`
---
## Running the Application
**Backend**
```bash
# Development
uvicorn app.main:app --reload --port 8000
# Run Knowledge Processor (in a separate terminal)
python -m app.workers.run_knowledge_processor
```
### Background processors
The API server only enqueues long-running jobs — a separate worker process
executes them. If no worker is running, jobs sit at `pending` forever and the
UI shows a progress bar that never advances.
| Worker | Command | Handles |
|---|---|---|
| Knowledge + FAQ | `python -m app.workers.run_knowledge_processor` | Knowledge ingestion (crawl, PDF, sitemap) **and** FAQ jobs |
| Ticket investigator | `python -m app.workers.ticket_investigator` | AI ticket investigation + ticket lifecycle |
| CRM sync | `python -m app.workers.crm_sync` | Lead push to HubSpot / Pipedrive |
Run each from the `backend/` directory with the virtualenv active.
**FAQ / Help Center processor.** FAQ generation and import jobs (Generate FAQs,
"Migrate an existing help center", PDF import) are drained by the *knowledge
worker* — there is no separate FAQ container. Both knowledge entrypoints pick
up the FAQ queue, so either one is enough:
```bash
# Recommended for local dev — knowledge and FAQ in one loop
python -m app.workers.run_knowledge_processor
# What Docker runs: knowledge and FAQ as independent asyncio tasks, so a long
# FAQ generation never blocks knowledge ingestion
python -m app.workers.knowledge_processor
# FAQ queue only — useful when debugging generation/import in isolation
python -m app.workers.faq_processor
```
Polls every 60s. On startup it fails any job left stuck in `processing` by a
previous crash, so a killed worker doesn't strand a job forever.
**Ticket investigator.** Runs two loops in one process — investigation runs
(polled every 15s) and ticket lifecycle/SLA sweeps (every 5 min):
```bash
python -m app.workers.ticket_investigator
```
Needs Redis (`REDIS_URL`) to push live `ticket_update` frames to dashboard
clients; without it the frontend falls back to polling. Orphaned runs are
reaped on startup.
**Under Docker**, these already run as services — `docker compose up` starts
them alongside the API:
```bash
docker compose logs -f knowledge_processor # knowledge + FAQ jobs
docker compose logs -f ticket_investigator
```
**Frontend**
```bash
# Development
npm run dev
# Build Widget for chat integration
npm run build:widget
# Build Web Client
npm run build:webclient
```
---
## Testing
**Backend**
```bash
cd backend && pytest tests/
```
**Frontend**
```bash
cd frontend && npm run test:unit
```
**End-to-end**: Playwright drives the real dashboard, widget and backend against a throwaway database and a fake LLM, all on `127.0.0.1`. Needs a local Postgres with pgvector and [Mailpit](https://mailpit.axllent.org).
```bash
cd e2e && npm ci && npx playwright install chromium && npm test
```
See [e2e/AUTHORING.md](e2e/AUTHORING.md) to add a test and [e2e/FEATURES.md](e2e/FEATURES.md) for what's covered.
---
## Deployment
### Docker Deployment (Recommended)
Pre-built Docker images are available:
```bash
# Pull images
docker pull chattermate/frontend:latest
docker pull chattermate/backend:latest
# Run with production compose
docker compose -f docker-compose.prod.yml up -d
```
Click for production deployment without Docker
**Backend**
```bash
pip install gunicorn
gunicorn app.main:app \
--workers 4 \
--worker-class uvicorn.workers.UvicornWorker \
--bind 0.0.0.0:8000 \
--access-logfile - \
--error-logfile - \
--log-level info \
--timeout 120
```
**Knowledge Processor (systemd)**
```bash
sudo tee /etc/systemd/system/chattermate-knowledge-processor.service << EOF
[Unit]
Description=ChatterMate Knowledge Processor
After=network.target
[Service]
User=chattermate
Group=chattermate
WorkingDirectory=/path/to/chattermate/backend
Environment="PATH=/path/to/chattermate/backend/venv/bin"
ExecStart=/path/to/chattermate/backend/venv/bin/python -m app.workers.run_knowledge_processor
Restart=always
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable chattermate-knowledge-processor
sudo systemctl start chattermate-knowledge-processor
```
**Frontend**
```bash
npm run build
# Serve using nginx or other web server
```
---
## FAQ
**What is ChatterMate?**
ChatterMate is an open-source AI customer support platform. It combines an AI chatbot (trained on your knowledge base) with human agents in a shared inbox, so AI handles routine questions 24/7 and hands off to your team when it matters.
**Is ChatterMate free and open source?**
Yes. The core platform is Apache-2.0 licensed — free for personal and commercial use, including self-hosted production deployments. There's also a free hosted plan at [app.chattermate.chat](https://app.chattermate.chat).
**Can the AI hand off conversations to a human agent?**
Yes — human handoff is a core feature, not an add-on. ChatterMate detects frustration or explicit requests for a human and transfers the conversation with full context, respecting business hours and agent availability.
**Does ChatterMate work with Shopify?**
Yes. Install it from the [Shopify App Store](https://apps.shopify.com/chattermate-chat) to answer order-status, shipping, and product questions directly from your store data. The widget also embeds on any other e-commerce or website platform with one line of code.
**Does ChatterMate work with WordPress?**
Yes. Download the [WordPress plugin](https://github.com/chattermate/chattermate-wordpress-plugin/releases/latest/download/chattermate-chat.zip), install it via **Plugins → Add New → Upload Plugin**, then enter your Widget ID under **Settings → ChatterMate Chat**. The chat launcher appears on your site with no theme edits. A WordPress.org directory listing is in progress.
**Can I self-host ChatterMate?**
Yes. Run the full stack (Postgres, Redis, backend, frontend) on your own infrastructure with `npm install -g chattermate-deploy` — see [Quick Start](#quick-start). Self-hosting gives you complete data ownership.
**Which AI models does ChatterMate support?**
OpenAI, Anthropic (Claude), Google Gemini, Mistral, xAI (Grok), DeepSeek, Groq, and any OpenAI-compatible endpoint (self-hosted, OpenRouter, Ollama) — bring your own API key, or enter a custom model ID for any model a provider supports. You can switch providers at any time without code changes.
**Can the AI chatbot capture and qualify leads?**
Yes. With [AI lead capture](#ai-lead-capture) the agent collects contact details during the conversation (with optional consent), writes a qualification summary, and can push the lead to HubSpot or Pipedrive. It works on the web widget and on messaging channels like WhatsApp and Instagram.
**Does ChatterMate work as a WhatsApp chatbot?**
Yes. Connect WhatsApp Business (Cloud API), plus Instagram, Facebook Messenger, Telegram, LINE, Slack, SMS and email. Every channel shares the same AI agent, inbox, human handoff and workflows.
**Can ChatterMate build a help center or knowledge base?**
Yes. It generates FAQ articles from your website, docs and PDFs with AI, and you review and publish them as a public, SEO-friendly [help center](#ai-generated-help-center) with AI search and the chat assistant built in.
**Does ChatterMate support MCP (Model Context Protocol)?**
Yes, both ways. Your AI agents can call any MCP server as a tool ([details](#connect-any-mcp-server)), and ChatterMate itself can be configured through its own [MCP server](https://docs.chattermate.chat/features/mcp-server).
---
## Roadmap
### Coming Soon
- 🔄 **Auto Follow-up System** - Automated follow-ups for idle customers
- 📘 **Customer Contact Management** - CRM-like contact organization
- 🤝 **Human Agent AI Suggestions** - AI-powered response suggestions for agents
- 📞 **AI Voice Chat** - Voice-enabled AI conversations
- 🔌 **More Integrations** - Zendesk, Intercom, and more
---
## Contributing
We welcome contributions! Here's how to get started:
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
### Development Guidelines
- Follow PEP 8 style guide
- Write tests for new features (and an [e2e](e2e/AUTHORING.md) spec when a user journey changes)
- Update documentation as needed
- Add type hints to new functions
---
## Support
- 📖 **Documentation**: [docs.chattermate.chat](https://docs.chattermate.chat)
- 🐛 **Issues**: [GitHub Issues](https://github.com/chattermate/chattermate/issues)
- 📧 **Email**: support@chattermate.chat
---
## License
ChatterMate follows an **open-core** model:
**Open Source Core ([Apache-2.0](https://opensource.org/licenses/Apache-2.0))**
- Free for personal and commercial use — including proprietary and SaaS deployments
- No source-disclosure or copyleft obligations
- Includes an explicit patent grant
- See [LICENSE](LICENSE) and [NOTICE](NOTICE)
**Enterprise features & support**
- Advanced/enterprise capabilities are provided separately under a commercial arrangement
- Priority support, warranties, and indemnification available
- Contact: [contact@chattermate.chat](mailto:contact@chattermate.chat)
Contributions are accepted under Apache-2.0 with a [Developer Certificate of Origin](DCO) sign-off — see [CONTRIBUTING.md](CONTRIBUTING.md).
---
Made with ❤️ by the ChatterMate team
Keywords: AI customer support, AI chatbot, Shopify chatbot, WordPress chatbot, WordPress chat plugin, ecommerce chatbot, customer support automation, open source help desk, live chat software, self-hosted chatbot, Intercom alternative, Zendesk alternative, Chatbase alternative, no-code chatbot builder, human handoff, Jira integration, Slack bot, multilingual chatbot, open source AI chatbot, WhatsApp chatbot, Instagram chatbot, omnichannel customer support, AI lead capture, lead generation chatbot, AI help center, AI knowledge base, FAQ generator, MCP server, Model Context Protocol, bring your own LLM, OpenAI chatbot, Claude chatbot, Chatwoot alternative
