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.

This guide walks you through running Chatwoot Custom on your own machine, creating a web widget inbox, and wiring up the ElevenLabs voice agent so visitors can start voice conversations from the chat widget.
You need an ElevenLabs account with a Conversational AI agent to use the voice features. The chat widget works without one — voice is optional.

​
Prerequisites

Before you start, make sure you have:
  • Docker Desktop installed and running — docker.com
  • Git to clone the repository
  • 8 GB RAM free (the Vite widget bundle is large)
  • 10 GB free disk space for the image and volumes

​
Setup

1

Clone the repository

Clone the repo and move into the project directory:
git clone <your-repo-url>
cd chatwoot-custom-master
2

Copy the environment template

Copy .env.example to .env and fill in the required values:
cp .env.example .env
Open .env in a text editor and set at minimum:
VariableWhat to put
FRONTEND_URLhttp://localhost:3000 for local testing, or your public domain
SECRET_KEY_BASEA long random string — generate one (see below)
POSTGRES_PASSWORDA strong password for the database
REDIS_PASSWORDA strong password for Redis; also update REDIS_URL to match
Generate a SECRET_KEY_BASE:
docker run --rm chatwoot/chatwoot:latest rails secret
Paste the output into .env.
Never reuse the example value in production. A weak or shared SECRET_KEY_BASE allows session forgery.
3

Pull the pre-built image or build locally

Option A — Pre-built image (fastest)Pull the image from Docker Hub so Compose can use it without building:
docker pull jatin4002/chatwoot-custom:latest
The docker-compose.yaml already references jatin4002/chatwoot-custom:latest, so no further changes are needed.Option B — Build locallyIf you want to modify the code or bake in a specific ElevenLabs agent ID at build time, run the build script instead:
./build.sh
You can also pass a custom agent ID, voice ID, agent name, and image tag:
./build.sh agent_XXXXXXX voice_YYYYYYY "My Agent" latest
The build takes 5–15 minutes depending on your machine. If it exits with code 139 (SIGSEGV), the build ran out of memory.
When building locally, update the image: line in docker-compose.yaml under rails and sidekiq to chatwoot-custom:latest and remove any build: block.
4

Start the services

Bring up all four services (postgres, redis, rails, sidekiq) in the background:
docker compose up -d
5

Open the dashboard and create your admin account

Wait about 60 seconds for Rails to run migrations, then open:
http://localhost:3000
The first visit shows an account-setup screen. Create your admin user and log in.
6

Create a web widget inbox

In the Chatwoot dashboard:
  1. Go to Settings → Inboxes → Add Inbox
  2. Choose Website
  3. Enter a name and your website URL
  4. Complete the wizard
You’ll land on the inbox’s configuration page, where you can copy the embed script to add to your site.
7

Enable the voice agent

Still on the inbox’s Configuration tab:
  1. Scroll to the Voice Agent section
  2. Toggle Enable Voice Agent on
  3. Set Provider to elevenlabs
  4. Leave API Key blank if your ElevenLabs agent is set to Public access; paste the key only for Private agents
  5. Paste your Agent ID — copy it from the ElevenLabs dashboard URL: 
    https://elevenlabs.io/app/conversational-ai/agents/agent_XXXXXXX
    Use the agent_XXXXXXX portion only
  6. Click Save Voice Agent Settings
The microphone button appears in the widget the next time a visitor opens it.
Voice and microphone features require HTTPS in production browsers. http://localhost:3000 works for local testing, but any public deployment must be served over HTTPS. Use ngrok, cloudflared, or your own domain with TLS.

​
Next steps

  • Embed the widget — copy the script from Settings → Inboxes → your inbox → Configuration and paste it before </body> on your website
  • Tail the logs — docker compose logs -f rails shows Rails output in real time
  • Restart after config changes — docker compose restart rails picks up changes without a full rebuild

​
Troubleshooting

SymptomFix
Call button doesn’t appearToggle off → save → toggle on → save. Then close and reopen the widget bubble.
Call connects then drops in ~3 sElevenLabs free-tier quota (~15 min/month) is exhausted. Check usage at elevenlabs.io/app/usage.
missing_permissions: convai_write in logsYour ElevenLabs API key needs “ElevenAgents → Write” permission. Edit the key in the ElevenLabs dashboard.
Voice transcript not appearingRun docker compose logs rails and search for voice_transcript. A 500 error will include the details.

Build docs developers (and LLMs) love

Get started for freeTalk to us