Skip to main content

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.

Chatwoot Custom is not a fork — it is an overlay. Every change lives inside the custom/ directory; no upstream Chatwoot file is ever edited. When you build the Docker image, COPY directives transplant the custom files onto their upstream paths at the last possible moment, so the finished container behaves like standard Chatwoot with additions, not a divergent branch.

​
The custom/ directory layout

custom/
├── backend/
│   ├── controllers/          # Rails controller overrides + concerns
│   ├── migrations/           # New ActiveRecord migrations
│   ├── models/               # Model overrides (web_widget.rb)
│   ├── routes.rb             # Full routes.rb replacement
│   └── views/                # Jbuilder and ERB view overrides
├── widget/
│   ├── api/                  # Axios API modules (contacts, conversation, inboxConfig)
│   ├── components/           # Vue component overrides + new components
│   ├── helpers/              # Custom axios instance
│   ├── i18n/                 # Locale overrides
│   ├── mixins/               # Shared Vue mixins
│   ├── store/
│   │   └── modules/          # Vuex module overrides + new modules
│   └── views/                # Vue page-level component overrides
└── dashboard/
    └── ConfigurationPage.vue # Agent-facing inbox settings override
SubdirectoryContents
custom/backend/Rails controllers, models, migrations, views, routes
custom/widget/Vue components, Vuex store modules, helpers, i18n
custom/dashboard/Agent-facing dashboard components

​
The golden rule

Never edit upstream Chatwoot files. Every customization must live inside custom/. Upstream edits create merge conflicts when you pull a new Chatwoot release and make it impossible to distinguish your changes from upstream code. The overlay pattern keeps your diff clean and your upgrade path open.
If you find yourself editing a file outside custom/, stop. Add the file to custom/ instead and add the corresponding COPY directive to the Dockerfile. The goal is zero modifications to the upstream source tree.

​
How the Dockerfile applies the overlay

The build uses two stages. Stage 1 clones upstream Chatwoot, copies all widget files from custom/widget/ and custom/dashboard/ over the cloned source, then runs vite build. Stage 2 starts from the official chatwoot/chatwoot:latest image and overlays the backend files: 
# Stage 2 backend overlay (excerpt)
COPY custom/backend/models/web_widget.rb         /app/app/models/channel/web_widget.rb
COPY custom/backend/views/_inbox.json.jbuilder   /app/app/views/api/v1/models/_inbox.json.jbuilder
COPY custom/backend/controllers/inboxes_controller.rb \
     /app/app/controllers/api/v1/accounts/inboxes_controller.rb
COPY custom/backend/controllers/conversations_controller.rb \
     /app/app/controllers/api/v1/widget/conversations_controller.rb
COPY custom/backend/controllers/concerns/website_token_helper.rb \
     /app/app/controllers/concerns/website_token_helper.rb
COPY custom/backend/routes.rb                    /app/config/routes.rb
COPY custom/backend/migrations/20260408000001_add_elevenlabs_to_channel_web_widgets.rb \
     /app/db/migrate/20260408000001_add_elevenlabs_to_channel_web_widgets.rb
COPY custom/backend/migrations/20260409000001_add_voice_agent_config_to_channel_web_widgets.rb \
     /app/db/migrate/20260409000001_add_voice_agent_config_to_channel_web_widgets.rb
Each COPY maps a custom/ file directly onto its upstream equivalent path inside /app. From Rails’ perspective the file simply exists at the expected location; it has no knowledge of the overlay.

​
How to upgrade Chatwoot

Because custom/ contains only your additions, upgrading is straightforward:
1

Check the upstream changelog

Review the Chatwoot release notes to identify any changes to files you override (controllers, models, views). Pay special attention to InboxesController, ConversationsController, and Channel::WebWidget.
2

Update the base image tag

In the Dockerfile, change FROM chatwoot/chatwoot:latest to the desired version tag, and update the git clone URL or tag in Stage 1 if you pin it.
3

Merge upstream changes into your custom files

For any upstream file you override, diff the new upstream version against your custom version and merge in new behavior that does not conflict with your additions.
4

Rebuild and test

Run ./build.sh and bring up the stack with docker compose up -d. Run database migrations and smoke-test the voice button and transcript endpoints.
Keep your custom controllers as thin as possible — add only what you need and call super or delegate to upstream methods where available. The less you override, the fewer conflicts you encounter on upgrade.

​
Explore each layer

Backend customizations

Migrations, model attributes, controller actions, views, and routes added by the overlay

Frontend customizations

Vue components, Vuex modules, API helpers, and the dashboard configuration page

Build and deploy

How build.sh and the multi-stage Dockerfile produce and ship the final image

Voice agent setup

End-to-end guide for enabling and configuring the ElevenLabs voice agent per inbox

Build docs developers (and LLMs) love

Get started for freeTalk to us