p24-infra Docs

whatsapp-group-bot-setup

5 min read

WhatsApp Group Bot — Evolution API + n8n Setup Guide

SUPERSEDED — Evolution API replaced by WAHA (NOWEB engine) running on Hostinger vps-h1. See hostinger/docker-compose.yml and docs/waha.md for current setup.

Stack: Evolution API (self-hosted) · n8n · Docker · Hetzner VPS
Cost: Free (open source) + one cheap prepaid SIM
Group support: ✅ Full — listen & respond to any WhatsApp group

Prerequisites

  • Hetzner VPS with Docker + Docker Compose installed
  • n8n already running (with a public HTTPS URL)
  • A dedicated phone number (prepaid SIM recommended — not your main number)
  • WhatsApp installed on any phone with that number

Step 1 — Deploy Evolution API

1.1 Clone and configure

git clone https://github.com/EvolutionAPI/evolution-api.git
cd evolution-api
cp .env.example .env

1.2 Edit .env

Open .env and set these key values:

# Your public domain for Evolution API
SERVER_URL=https://evolution.yourdomain.com
 
# Strong random string — this is your master API key
AUTHENTICATION_API_KEY=your-super-secret-key-here
 
# Enable the Manager UI
DEL_INSTANCE=false
 
# Optional: set to true to auto-start instances on restart
CLEAN_STORE_CLEANING_INTERVAL=7200
 
# Database (SQLite is fine for small scale)
DATABASE_ENABLED=false

Tip for your stack: If you already have a Redis container running, add:

REDIS_ENABLED=true
REDIS_URI=redis://redis:6379

1.3 Start with Docker Compose

docker compose up -d

Check it’s running:

docker compose logs -f
# Should show: "HTTP Server running on port 8080"

1.4 Expose via reverse proxy

Add to your Nginx/Caddy config:

Caddy:

evolution.yourdomain.com {
    reverse_proxy localhost:8080
}

Nginx:

server {
    listen 443 ssl;
    server_name evolution.yourdomain.com;
 
    location / {
        proxy_pass http://localhost:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

Step 2 — Connect Your WhatsApp Number

2.1 Open Evolution Manager UI

Visit: https://evolution.yourdomain.com/manager

Login with your AUTHENTICATION_API_KEY.

2.2 Create an instance

  1. Click “New Instance”
  2. Name it (e.g. groupbot)
  3. Click “Create”

2.3 Scan QR code

  1. Click on your instance → “Connect”
  2. A QR code appears
  3. On your phone: WhatsApp → Linked Devices → Link a Device
  4. Scan the QR code

✅ Status changes to “open” — you’re connected.

After this, the phone can go in a drawer. Evolution API maintains the session on your server.

2.4 Add the bot to your WhatsApp group

In WhatsApp on your phone, open the target group → Add Participants → add the bot number.

Step 3 — Register Webhook in Evolution API

This tells Evolution API to forward all incoming messages to n8n.

curl -X POST https://evolution.yourdomain.com/webhook/set/groupbot \
  -H "apikey: your-super-secret-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-n8n-domain.com/webhook/whatsapp-group",
    "enabled": true,
    "events": ["MESSAGES_UPSERT"]
  }'

Expected response:

{ "webhook": { "enabled": true, "url": "https://...", "events": ["MESSAGES_UPSERT"] } }

Step 4 — Import n8n Workflow

  1. In n8n: top-right menu → Import from file
  2. Select whatsapp-group-bot.json
  3. The workflow appears with all nodes connected

Step 5 — Configure the Workflow Nodes

5.1 Claude AI Response node

Add credentials:

  • Type: HTTP Header Auth
  • Name: Anthropic
  • Header: x-api-key
  • Value: your Anthropic API key

5.2 Send Reply to Group node

Replace the placeholders in the URL and headers:

PlaceholderReplace with
YOUR_EVOLUTION_DOMAINevolution.yourdomain.com
YOUR_INSTANCE_NAMEgroupbot
YOUR_EVOLUTION_API_KEYyour master API key

5.3 Adjust mention filter (optional)

By default the bot only responds when mentioned (@bot in message text).

To respond to ALL group messages: delete the “Filter: Bot Mentioned?” node and connect “Filter: Has Text” directly to “Claude AI Response”.

To respond only to specific keywords: replace the mention filter with:

{{ $json.text.toLowerCase().includes('help') }}

Step 6 — Activate & Test

  1. In n8n, toggle the workflow to Active
  2. Send a message in the WhatsApp group mentioning @bot
  3. Watch the execution log in n8n
  4. Bot should reply within a few seconds

Workflow Architecture

Webhook Trigger (POST /whatsapp-group)
    │
    ├──▶ Respond 200 OK  (immediate ack to Evolution API)
    │
    └──▶ Filter: Group Messages Only  (@g.us check + not from bot itself)
              │
              └──▶ Extract Message Data  (text, groupId, sender, messageId)
                        │
                        └──▶ Filter: Has Text
                                  │
                                  └──▶ Filter: Bot Mentioned?
                                            │
                                            └──▶ Claude AI Response
                                                      │
                                                      └──▶ Extract AI Response
                                                                │
                                                                └──▶ Send Reply to Group
                                                                      (quoted reply in group)

Troubleshooting

Bot not receiving messages

# Check Evolution API is running
docker compose ps
 
# Check webhook is registered
curl https://evolution.yourdomain.com/webhook/find/groupbot \
  -H "apikey: your-super-secret-key-here"
 
# Check n8n webhook is active (not just test mode)
# In n8n: workflow must be ACTIVE, not just in test/listen mode

Session disconnected

WhatsApp occasionally logs out the session. To reconnect:

# Via API
curl -X DELETE https://evolution.yourdomain.com/instance/logout/groupbot \
  -H "apikey: your-key"
 
# Then rescan QR in Manager UI

Messages arriving but no reply

Check n8n execution log for errors:

  • 401 on Claude call → wrong API key
  • 404 on Evolution send → wrong instance name or domain
  • Empty text field → message type not supported (e.g. sticker, poll)

Rate limiting / flooding

Add a Wait node (1-2 seconds) before the send node to avoid triggering WhatsApp spam detection.

Docker Compose Integration

If you want Evolution API in your existing docker-compose.yml:

services:
  # ... your existing services (n8n, redis, etc.)
 
  evolution-api:
    image: atendai/evolution-api:latest
    container_name: evolution-api
    restart: unless-stopped
    ports:
      - "8080:8080"
    env_file:
      - ./evolution-api/.env
    volumes:
      - evolution_store:/evolution/store
      - evolution_instances:/evolution/instances
 
volumes:
  evolution_store:
  evolution_instances:

Security Notes

  • Keep AUTHENTICATION_API_KEY strong and secret
  • Don’t expose Evolution API without HTTPS
  • The bot number should be dedicated — not your personal WhatsApp
  • Evolution API uses WhatsApp Web protocol (unofficial) — use a spare number to avoid bans
  • Avoid sending too many messages too fast (add delays for bulk operations)

Useful Evolution API Endpoints

# List all instances
GET /instance/fetchInstances
 
# Check connection status
GET /instance/connectionState/groupbot
 
# Get all groups the number is in
GET /group/fetchAllGroups/groupbot?getParticipants=false
 
# Send a message manually
POST /message/sendText/groupbot
Body: { "number": "GROUP_ID@g.us", "text": "Hello group!" }

Generated: May 2026 | Evolution API v2.x | n8n v1.x

Graph View

Backlinks