baileys-antiban-evolution

Anti-ban protection for Evolution API — brings baileys-antiban's rate limiting, warmup, and session stability to Evolution API users.

Evolution API (8k⭐, 3.7M downloads/month via n8n) wraps Baileys with a REST API but ships zero anti-ban protection. Users report constant bans (#2228, #1870, #2437). This adapter fixes that.

No fork, no PR upstream. Just install, apply at startup, done.

Quick Install (Docker / n8n Users)

Add 5 lines to your docker-compose.yml:

services:
  evolution-api:
    image: atendai/evolution-api:latest
    command: >
      sh -c "
        npm install --no-save baileys-antiban baileys-antiban-evolution &&
        node --require baileys-antiban-evolution/dist/index.js dist/main.js
      "
    environment:
      - ANTIBAN_PRESET=conservative  # Add this line
      # ... your existing Evolution env vars

Before: Sessions banned in 24-48 hours after bulk operations.
After: Sessions survive weeks with transparent rate limiting.

Advanced Usage (Developers)

Installation

npm install baileys-antiban-evolution baileys-antiban

Apply at Startup

Add this to your Evolution API startup script before Evolution boots:

import { applyAntibanToEvolution } from 'baileys-antiban-evolution';
import { AntiBan } from 'baileys-antiban';

const antiban = new AntiBan({
  preset: 'conservative', // or 'moderate' | 'aggressive'
});

await applyAntibanToEvolution(antiban);

// Now start Evolution normally

Full example: examples/nodejs-startup.ts

Configuration

await applyAntibanToEvolution(antiban, {
  guardSendMessage: true,          // Rate-limit sendMessage()
  guardSendMessageWithTyping: true, // Rate-limit sendMessageWithTyping()
  guardTextMessage: true,           // Rate-limit textMessage()
  logger: console,                  // Optional: custom logger
});

Presets:

• conservative: 2 msg/sec, 7-day warmup (safest)
• moderate: 5 msg/sec, 5-day warmup
• aggressive: 10 msg/sec, 3-day warmup (higher risk)

Tune via env vars:

ANTIBAN_PRESET=conservative
ANTIBAN_MAX_QPS=2
ANTIBAN_WARMUP_DAYS=7

Full config: examples/env-config.example.env

What It Does

1. Rate limiting: Enforces configurable QPS (queries per second) with Gaussian jitter on all outbound sends
2. Warmup phase: Scales rate limits for new sessions over 3-7 days (mimics human behavior)
3. Session health monitoring: Catches HKDF key drift before Bad MAC bans occur
4. Device fingerprint randomization: Varies clientPayload per session to avoid detection

Why This Fixes Evolution Issues

Issue #2228 — Bulk Number Checking Bans

"Lacks rate limiting... banned after checking 50 numbers"

Fixed: Rate limiter enforces 2-10 msg/sec ceiling with jitter. No more hammering WhatsApp's servers.

Issue #1870 — Constant Banning

"Warmup itself triggers bans"

Fixed: 7-day warmup phase starts at 0.2 msg/sec, gradually scales to full rate. New sessions behave like real users.

Issue #2437 — QR/Pairing Failures

"Session dies after 24h"

Fixed: Session health monitor detects HKDF drift (Bad MAC precursor) and triggers proactive reconnect.

Performance Impact

Honest: Adds ~50-200ms latency per send (configurable via jitterMs).

Worth it: Bans cost weeks of recovery. 200ms is negligible vs. losing access.

For high-throughput use cases, use aggressive preset (10 msg/sec) or disable specific guards:

await applyAntibanToEvolution(antiban, {
  guardSendMessage: true,
  guardSendMessageWithTyping: false, // Skip typing guard if you don't use it
  guardTextMessage: false,
});

Limitations

1. Evolution version compatibility: Designed for Evolution v2.x (tested against v2.3.7). Class shape verified live against main on 2026-04-26. Re-test on major version bumps.
2. Method coverage in v0.1: We rate-limit textMessage, sendMessage, sendMessageWithTyping, and connectToWhatsapp. Evolution exposes ~12 public REST message methods total — mediaMessage, audioWhatsapp, pollMessage, contactMessage, locationMessage, etc. are NOT yet rate-limited in this release. Most ban risk is text-bulk-sending which textMessage covers, but if your workflow is media-heavy, wait for v0.2 or open an issue.
3. Not a silver bullet: WhatsApp's ban detection evolves. This reduces risk but doesn't guarantee immunity.
4. Monkey-patching: Wraps Evolution's internal methods at runtime. If Evolution changes class structure, adapter may need updates.

Examples

• Docker Compose — Full n8n + Evolution + anti-ban stack
• Node.js Startup — Programmatic usage
• Env Config — All tunable parameters

How It Works

Uses monkey-patching to wrap Evolution's WhatsAppBaileysService class at runtime:

1. connectToWhatsapp() — Wraps socket creation, applies session health monitoring
2. sendMessage() — Enforces rate limit before delegating to original
3. sendMessageWithTyping() — Same rate limit enforcement
4. textMessage() — Same rate limit enforcement

If rate limit exceeded, throws HTTP 429 error:

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Anti-ban protection active. Retry after 5s"
}

REST clients (n8n, Make, etc.) handle 429s gracefully with exponential backoff.

License

MIT — same as baileys-antiban and Evolution API.

Credits

Built by Hannes (Kobus) Wentzel.

Pairs with:

• baileys-antiban — Core anti-ban engine
• Evolution API — Baileys REST wrapper

Roadmap

• [ ] Auto-detect Evolution version, log compatibility warning
• [ ] Support for Evolution v3.x (when released)
• [ ] Metrics endpoint (/antiban/stats) for monitoring rate limit usage
• [ ] Webhooks for ban warnings (session health degradation alerts)

Contributions welcome. Issues/PRs to GitHub.