> ## Content Index
> Fetch the complete content index at: https://www.blog.nestict.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# Running Chatwoot on EasyPanel with WhatsApp Integration – Fixing Common Issues
- URL: https://www.blog.nestict.com/running-chatwoot-on-easypanel-with-whatsapp-integration-fixing-common-issues/
- Published: 2025-08-23T08:25:03.000Z
- Updated: 2025-08-23T08:25:03.000Z
- Author: Nestict Infotech CSR
- Tags: Technology, Featured

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.