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.
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 varsBefore: Sessions banned in 24-48 hours after bulk operations.
After: Sessions survive weeks with transparent rate limiting.
npm install baileys-antiban-evolution baileys-antibanAdd 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 normallyFull example: examples/nodejs-startup.ts
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=7Full config: examples/env-config.example.env
- Rate limiting: Enforces configurable QPS (queries per second) with Gaussian jitter on all outbound sends
- Warmup phase: Scales rate limits for new sessions over 3-7 days (mimics human behavior)
- Session health monitoring: Catches HKDF key drift before Bad MAC bans occur
- Device fingerprint randomization: Varies
clientPayloadper session to avoid detection
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.
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,
});- Evolution version compatibility: Designed for Evolution v2.x (tested against v2.3.7). Class shape verified live against
mainon 2026-04-26. Re-test on major version bumps. - Method coverage in v0.1: We rate-limit
textMessage,sendMessage,sendMessageWithTyping, andconnectToWhatsapp. 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 whichtextMessagecovers, but if your workflow is media-heavy, wait for v0.2 or open an issue. - Not a silver bullet: WhatsApp's ban detection evolves. This reduces risk but doesn't guarantee immunity.
- Monkey-patching: Wraps Evolution's internal methods at runtime. If Evolution changes class structure, adapter may need updates.
- Docker Compose — Full n8n + Evolution + anti-ban stack
- Node.js Startup — Programmatic usage
- Env Config — All tunable parameters
Uses monkey-patching to wrap Evolution's WhatsAppBaileysService class at runtime:
connectToWhatsapp()— Wraps socket creation, applies session health monitoringsendMessage()— Enforces rate limit before delegating to originalsendMessageWithTyping()— Same rate limit enforcementtextMessage()— 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.
This package is published from GitHub Actions with npm provenance via sigstore. Every release tag (v*) produces a signed attestation tying the published artifact back to the exact source commit + workflow run.
To verify a downloaded version:
npm install baileys-antiban-evolution
npm view baileys-antiban-evolution@<version> dist.integrity
# or fetch the attestation:
gh attestation verify $(npm pack baileys-antiban-evolution@<version>) --owner kobie3717Inspired by post-lotusbail (Sept 2025, 56K-download supply chain attack on a baileys variant) — the only Baileys-ecosystem package shipping signed releases as of v0.1+.
MIT — same as baileys-antiban and Evolution API.
Built by Hannes (Kobus) Wentzel.
Pairs with:
- baileys-antiban — Core anti-ban engine
- Evolution API — Baileys REST wrapper
- 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.