Chatwoot Custom is a production-ready overlay on top of the open-source Chatwoot platform that adds a real-time AI voice agent directly inside the live-chat widget. Visitors can switch from typing to talking in a single click — and every voice turn is automatically posted as a message in the conversation, so your support team sees exactly what was said.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/jAtInn71/chatwoot-costom/llms.txt
Use this file to discover all available pages before exploring further.
How it works
The project follows an overlay architecture: all custom code lives in acustom/ directory and is layered on top of upstream Chatwoot at build time. The original Chatwoot files are never modified, which means you can pull future Chatwoot upgrades without merge conflicts.
The voice agent is configured per inbox from the Chatwoot dashboard — no environment variables or rebuilds required after the first deploy. Admins paste their ElevenLabs Agent ID into the inbox’s Configuration tab, toggle voice on, and the microphone button appears immediately in the widget for all visitors.
What’s included
Quick start
Run Chatwoot Custom locally in under five minutes using Docker Compose.
Deployment
Deploy using the pre-built Docker image or build your own from source.
Voice agent
Configure the ElevenLabs voice agent per inbox from the dashboard.
Widget embedding
Add the chat and voice widget to any website with a single script tag.
Key features
AI voice agent in the chat widget A microphone button appears next to the text input when it’s empty. Clicking it starts a real-time voice conversation with your ElevenLabs agent. The button shows only when the voice agent is enabled and configured for the inbox. Automatic voice transcripts Every completed utterance — both visitor and AI — is posted into the Chatwoot conversation as a message bubble. User turns appear as incoming messages; AI turns appear as outgoing messages. Support agents get a full record of the call without leaving the dashboard. Soft exit without iframe reload When a visitor exits the chat, the widget resets state in place instead of reloading the iframe. This prevents a white flash and keeps host pages that listen for theexitChat postMessage working correctly.
Per-inbox dashboard configuration
Voice agent settings (provider, Agent ID, optional API key) are stored per inbox in the database and served to the widget at runtime. No rebuild is needed to change agent configuration.
Technology stack
| Layer | Technology |
|---|---|
| Backend | Ruby on Rails 7 |
| Frontend widget | Vue 3 + Vite |
| Background jobs | Sidekiq |
| Database | PostgreSQL 14 with pgvector |
| Cache / queues | Redis 7 |
| Voice provider | ElevenLabs Conversational AI |
| Packaging | Docker + Docker Compose |
The custom/ directory pattern
All customizations are isolated undercustom/:
custom/widget/— Vue components, Vuex store modules, and helpers for the visitor-facing widgetcustom/backend/— Rails controllers, models, migrations, and viewscustom/dashboard/— Agent-facing dashboard additions (inbox configuration page)
Dockerfile copies these files over their upstream counterparts at build time. Upgrading Chatwoot is safe because none of the upstream files are touched.