WhatsApp + ChatWoot - Installation Guide

July 11, 2025 in Apps, ChatWoot by devlikeapro5 minutes

Overview

Complete guide to install and set up production-ready WAHA and Chatwoot instances on your own infrastructure!

ChatWoot Articles

Series of articles about WhatsApp and ChatWoot integration using 🧩 ChatWoot App:

You can follow them one by one or skip some parts if you don’t need them.

After completing the installation guide, you’ll have:

WAHA on http://localhost:3000
ChatWoot on http://localhost:3009

Disclaimer

This project is not affiliated, associated, authorized, endorsed by, or in any way officially connected with WhatsApp, ChatWoot, or any of their respective subsidiaries or affiliates. The official websites can be found at https://whatsapp.com and https://chatwoot.com.

For businesses seeking to integrate with WhatsApp for critical applications, we strongly recommend using officially supported methods.

Requirements

Hardware: VM, VPS, or laptop with minimum 2 CPU and 4GB RAM
Operating System: Debian or Ubuntu based distributions.

Using a VPS or VM via SSH?

You need to forward ports so you can access remote server ports from your laptop.

Connect to the server using the command:

ssh -L 3000:localhost:3000 -L 3009:localhost:3009 {user}@{server}

Steps to Deploy

Step 0: Add DNS Aliases

First, we need to add DNS Aliases so everything works as inside docker containers.

👉 Run the below commands on YOUR LAPTOP/PC, NOT on the VPS or VM:

# Add
echo "127.0.0.1 chatwoot" | sudo tee -a /etc/hosts
echo "127.0.0.1 waha" | sudo tee -a /etc/hosts

# Check it worked - you must see the line like:
# 64 bytes from localhost (127.0.0.1): ...
ping chatwoot
ping waha

# Add
echo "127.0.0.1 chatwoot" | sudo tee -a /etc/hosts
echo "127.0.0.1 waha" | sudo tee -a /etc/hosts

# Check it worked - you must see the line like:
# 64 bytes from localhost (127.0.0.1): ...
ping chatwoot
ping waha

Run PowerShell as Admin and execute:

Add-Content -Path "$env:SystemRoot\System32\drivers\etc\hosts" -Value "`n127.0.0.1 chatwoot"
Add-Content -Path "$env:SystemRoot\System32\drivers\etc\hosts" -Value "`n127.0.0.1 waha"

ping chatwoot
ping waha

Step 1: Install Docker

# example in ubuntu
apt-get update
apt-get upgrade
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
apt install docker-compose-plugin

Step 2: Download the Required Files

# Download the env files
wget -O .waha.env https://raw.githubusercontent.com/devlikeapro/waha/refs/heads/core/docker-compose/chatwoot/.waha.env
wget -O .chatwoot.env https://raw.githubusercontent.com/devlikeapro/waha/refs/heads/core/docker-compose/chatwoot/.chatwoot.env
# Download docker-compose
wget -O docker-compose.yaml https://raw.githubusercontent.com/devlikeapro/waha/refs/heads/core/docker-compose/chatwoot/docker-compose.yaml

Step 3: Configure Environment Variables

Now you can tweak .waha.env, .chatwoot.env and docker-compose.yaml according to your preferences.

Here are a few environment variables we suggest that you change before going forward (in this guide we’ll use the default values):

WAHA_API_KEY_PLAIN=00000000000000000000000000000000
WAHA_API_KEY=sha512:98b6d128682e280b74b324ca82a6bae6e8a3f7174e0605bfd52eb9948fad8984854ec08f7652f32055c4a9f12b69add4850481d9503a7f2225501671d6124648
WAHA_DASHBOARD_USERNAME=admin
WAHA_DASHBOARD_PASSWORD=11111111111111111111111111111111
WHATSAPP_SWAGGER_USERNAME=admin
WHATSAPP_SWAGGER_PASSWORD=11111111111111111111111111111111

Do Not Use Default API Keys or Passwords!

Even if you’re running WAHA on a private server and think the IP is unknown - it’s straightforward for attackers to find and exploit it to send spam or abuse your WhatsApp sessions.

Always set strong, random values (see a guide below) for:

WAHA_API_KEY
WAHA_DASHBOARD_PASSWORD
WHATSAPP_SWAGGER_PASSWORD - you can the same as for WAHA_DASHBOARD_PASSWORD

👉 How to Generate and Hash Api-Key

Generate Api Key using uuid4 and remove - from it (or find a tool online)

uuidgen | tr -d '-'
> 00000000000000000000000000000000

Hash it using sha512 (or find a tool online)

echo -n "00000000000000000000000000000000" | shasum -a 512
> 98b6d128682e280b74b324ca82a6bae6e8a3f7174e0605bfd52eb9948fad8984854ec08f7652f32055c4a9f12b69add4850481d9503a7f2225501671d6124648  -

WAHA_API_KEY=sha512:98b6...24648 - SHA512 hash in hex format.
X-Api-Key: 0000...0000 - Api Key that you need to send in X-Api-Key header.
- Keep it in secret, do not add it to .env

👉 How to Generate and Hash Api-Key

Generate Api Key using uuid4 and remove - from it (or find a tool online)

uuidgen | tr -d '-'
> 00000000000000000000000000000000

Hash it using sha512 (or find a tool online)

echo -n "00000000000000000000000000000000" | shasum -a 512
> 98b6d128682e280b74b324ca82a6bae6e8a3f7174e0605bfd52eb9948fad8984854ec08f7652f32055c4a9f12b69add4850481d9503a7f2225501671d6124648  -

WAHA_API_KEY=sha512:98b6...24648 - SHA512 hash in hex format.
X-Api-Key: 0000...0000 - Api Key that you need to send in X-Api-Key header.
- Keep it in secret, do not add it to .env

Step 4: Pull Docker Images

If you got the ➕ WAHA Plus , use the following commands:

docker login -u devlikeapro -p {KEY}
docker compose pull
docker logout

👉 Go to Docker Image Configurator to generate the command with the right version.

In docker-compose.yaml change image: devlikeapro/waha-plus to image: devlikeapro/waha
Run the command:

docker compose pull

If you’re using ARM CPU (like Apple M1/M2, Raspberry Pi etc.).

If you got the ➕ WAHA Plus:

In docker-compose.yaml change image: devlikeapro/waha-plus to image: devlikeapro/waha-plus:arm
Run the commands:

docker login -u devlikeapro -p {KEY}
docker pull devlikeapro/waha-plus:arm
docker logout

👉 Go to Docker Image Configurator to generate the command with the right version.

If you want to run WAHA Core:

In docker-compose.yaml change image: devlikeapro/waha-plus to image: devlikeapro/waha:arm
Run the commands:

docker compose pull

Step 5: Prepare ChatWoot Database

docker compose run --rm chatwoot bundle exec rails db:chatwoot_prepare

Step 6: Start the Services

docker compose up -d

Step 7: Access Your WAHA

Open http://localhost:3000/dashboard with credentials:

User: admin
Password: 11111111111111111111111111111111

Add Api Key to your worker:

Api-Key: 00000000000000000000000000000000

Step 8: Access Your ChatWoot

Open and finish the onboarding guide on http://localhost:3009/

What is next?

👉 Connect WhatsApp to ChatWoot in WhatsApp + ChatWoot - Configuration Guide