Running Chatwoot on EasyPanel with WhatsApp Integration – Fixing Common Issues

Cloud Services Support
1

Running Chatwoot on EasyPanel with WhatsApp Integration – Fixing Common Issues
Running Chatwoot on EasyPanel with WhatsApp Integration – Fixing Common Issues1200×1200 89.5 KB

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

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

Cause: Misconfigured FRONTEND_URL or RAILS_STORAGE_SERVICE_URL.

:white_check_mark: Fix:

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

:red_circle: Issue 2: Garbled text like ˆ\tAF

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

:white_check_mark: Fix:

  • Ensure your DB is created with utf8mb4_general_ci.

  • Add to .env:LANG=en_US.UTF-8

  • Restart the container.

:red_circle: Issue 3: hmac_verified:false

Cause: Webhook verification token mismatch.

:white_check_mark: Fix:

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

  • Revalidate the webhook.

:red_circle: Issue 4: Attachments disappearing after restart

Cause: Active Storage is writing to ephemeral container storage.

:white_check_mark: 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.

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