WhatsApp AI Gateway

Production-ready WhatsApp AI Gateway built on Baileys.

Current release:

chatbot-v2-tool-system

Active feature branch:

work/v2-async-safety-and-docs

Stacked on:

main

Release verification baseline:

75 test files passed
659 tests passed
Docker runtime reached READY
Manual local WhatsApp smoke passed
Manual Docker WhatsApp smoke passed

Documentation

Read these in order:

1. docs/installation.md for setup, configuration, testing, local runtime, Docker runtime, and troubleshooting.
2. docs/production-handover.md for release handover, production checks, regression map, and branch cleanup.
3. docs/async-job-workflow.md for the durable async job design and the rule that delayed replies require persisted jobs.
4. docs/tool-configuration-guide.md for accepted tool JSON formats, routing metadata, schema options, access rules, and tool testing.
5. docs/config-write-commands.md for v2.2 safe config mutation commands.
6. docs/production-monitoring.md for v2.6 runtime health, Docker healthcheck, log rotation, and data backup/restore.
7. docs/baileys-resilience.md for v2.7 reconnect/session resilience.
8. docs/docker.md for Docker-specific notes.
9. docs/npm-install.md for global CLI package checks.
10. docs/connector-implementation-playbook.md for future connector guidance.

Quick local verification

npm install
npm run build
npm test
npm run cli -- doctor
npm run cli -- smoke
npm run cli -- config validate
npm run cli -- health

Expected release baseline:

75 test files passed
659 tests passed

Config write commands

The v2.2 branch adds safe writes for config/chatbot.config.json only:

npm run cli -- config set <path> <json-value>
npm run cli -- config unset <path>
npm run cli -- config backup
npm run cli -- config restore <backup-file>
npm run cli -- config diff
npm run cli -- config validate

Config writes create backups, validate before saving, reject unsafe paths, reject secret-like values, and leave config/tools.chatbot.json read-only for this milestone.

Production monitoring commands

The v2.6 branch adds health and runtime data operations:

npm run cli -- health
npm run cli -- health --quiet
bash scripts/backup-data.sh
bash scripts/restore-data.sh <backup-file> --yes
bash scripts/check-runtime.sh

Docker healthchecks now use the real CLI health command, and Compose includes bounded log files.

Baileys resilience

The v2.7 branch strengthens reconnect behavior:

• Bad sessions are treated as terminal instead of reconnect-looping.
• Terminal disconnects clear pending reconnect timers.
• Repeated reconnect schedules trigger a rapid-loop pause.
• Restart-required events still reconnect immediately unless the rapid-loop circuit breaker is active.

Run the targeted reconnect test:

npm test -- src/gateway/reconnect/__tests__/manager.test.ts

Local runtime

npm run start:worker

Wait for:

READY — processing messages now

Docker runtime

docker compose down
docker compose build --no-cache
docker compose run --rm wa-chatbot node dist/cli/index.js doctor
docker compose run --rm wa-chatbot node dist/cli/index.js config validate
docker compose run --rm wa-chatbot node dist/cli/index.js health
docker compose run --rm wa-chatbot node dist/cli/index.js smoke
docker compose up

Stop Docker:

docker compose down

Release-critical behavior

• Owner diagnostics and tool commands work in owner self-chat.
• Normal user chats receive normal user-facing replies.
• Natural-language current-information questions can route through tools when needed.
• Group replies follow configured activation rules.
• Docker persists auth, database, and media in ./data and mounts config read-only from ./config.
• AI replies are sanitized before WhatsApp output so model preambles and tool artifacts are not sent to users.
• Health checks must not start WhatsApp, pair WhatsApp, or send messages.
• Reconnect logic must not loop forever after bad session, logout, device removal, connection replacement, forbidden, or multi-device mismatch.

Future work not included in the v2 release tag

• Arbitrary custom HTTP tool execution.
• npm publishing.
• Additional provider fallback tuning for weak web/news results.
• Custom tool connector system.