Running Chatwoot on EasyPanel with WhatsApp Integration – Fixing Common Issues

If you’re looking to set up Chatwoot as your customer messaging platform on EasyPanel, integrating it with WhatsApp Cloud API is a great choice. However, many users run into problems during the setup: garbled text, broken image/file links, and webhook verification errors.

This guide walks you through the correct configuration, common pitfalls, and fixes so you can get a smooth Chatwoot + WhatsApp integration.

Why Chatwoot + EasyPanel?

• EasyPanel lets you deploy and manage Docker apps without needing to memorize long Docker commands.
• Chatwoot is an open-source customer engagement suite that supports email, WhatsApp, Facebook, Instagram, Telegram, and more.

When you combine the two, you get an easy-to-manage messaging platform with enterprise flexibility.

Step 1: Deploy Chatwoot on EasyPanel

1. Log in to your EasyPanel instance.
2. Create a new app → select Docker image → use:chatwoot/chatwoot:latest
   
3. Set your environment variables (.env) in EasyPanel. At minimum:RAILS_ENV=production
   FRONTEND_URL=https://chatwoot.yourdomain.com
   SECRET_KEY_BASE=<generate with `openssl rand -hex 64`>
   POSTGRES_HOST=your-postgres
   POSTGRES_USERNAME=chatwoot
   POSTGRES_PASSWORD=yourpassword
   REDIS_URL=redis://your-redis:6379/1
   LANG=en_US.UTF-8
   ACTIVE_STORAGE_SERVICE=local
   RAILS_STORAGE_SERVICE_URL=https://chatwoot.yourdomain.com
   
4. Map storage to persist uploaded files:/app/storage → /var/lib/chatwoot/storage

Step 2: Connect Chatwoot with WhatsApp Cloud API

1. Go to Meta Developers.
2. Create a WhatsApp app → generate your WhatsApp Business Account ID, Phone number ID, and Permanent Access Token.
3. In Chatwoot, go to Inboxes → Add Inbox → WhatsApp Cloud API.
4. Fill in:
   • Phone number ID
   • WABA ID
   • Access Token
   • Verify Token (you define this – must match your .env)

Add to .env:

WHATSAPP_VERIFY_TOKEN=mysecuretoken
Save, and Meta will validate your webhook.

Step 3: Fixing Common Errors

🔴 Issue 1: Broken attachment links (http://https/rails/...)

Cause: Misconfigured FRONTEND_URL or RAILS_STORAGE_SERVICE_URL.

✅ Fix:

FRONTEND_URL=https://chatwoot.yourdomain.com
RAILS_STORAGE_SERVICE_URL=https://chatwoot.yourdomain.com
Rebuild and redeploy.

🔴 Issue 2: Garbled text like ˆ\tAF

Cause: Encoding mismatch (WhatsApp sends UTF-8, but DB or environment isn’t aligned).

✅ Fix:

• Ensure your DB is created with utf8mb4_general_ci.
• Add to .env:LANG=en_US.UTF-8
  
• Restart the container.

🔴 Issue 3: hmac_verified:false

Cause: Webhook verification token mismatch.

✅ Fix:

• In Meta → Webhooks, confirm your Verify Token matches Chatwoot’s .env:WHATSAPP_VERIFY_TOKEN=mysecuretoken
  
• Revalidate the webhook.

🔴 Issue 4: Attachments disappearing after restart

Cause: Active Storage is writing to ephemeral container storage.

✅ Fix:

• Mount a volume in EasyPanel:/app/storage → /var/lib/chatwoot/storage
  
• Or switch to S3/MinIO:ACTIVE_STORAGE_SERVICE=s3
  AWS_ACCESS_KEY_ID=xxx
  AWS_SECRET_ACCESS_KEY=xxx
  AWS_REGION=us-east-1
  AWS_BUCKET=my-chatwoot-files
  

Step 4: Restart and Test

After applying fixes, restart your Chatwoot service in EasyPanel:

docker-compose down
docker-compose up -d --build
Then:

• Send a test message from WhatsApp → check if it arrives in Chatwoot.
• Send an image/file → confirm it loads correctly.

Wrapping Up

Running Chatwoot on EasyPanel is straightforward, but WhatsApp integration introduces a few tricky issues: malformed URLs, encoding problems, webhook verification, and storage persistence. By correcting your .env variables and database encoding, you can ensure smooth communication between Chatwoot and WhatsApp.

👉 With this setup, your team can manage all customer conversations from a single inbox — across WhatsApp and other channels.