waha/AGENTS.md

WAHA Agent Playbook

This guide summarizes how to explore, modify, and validate the WhatsApp HTTP API (WAHA) codebase when assisting as an automation or coding agent.

Product & Variants

• WAHA ships in Core and Plus editions
• Core lives under src/core and supports the default session with minimal media features
• Plus extends core via src/plus to add multi-session orchestration, richer media handling, and external storage integrations
• Core code must remain free from Plus-only references (pre-commit hook rejects "plus" in core files)
• Commit subjects: changes that touch src/plus require [PLUS] … prefix; everything else uses [core] …

Tech Stack

• Runtime: Node.js 22.x, Yarn 3.6 (Berry)
• Framework: NestJS v11 with dependency injection and modular controllers in src/api
• Engines: WhatsApp engines are abstracted (WEBJS, GOWS, NOWEB, WPP). Core uses SessionManagerCore; Plus swaps to SessionManagerPlus with extra storage backends (Mongo/Postgres/SQLite)
• ESM Bridge: ESM-only dependencies (Baileys) load through src/vendor/esm.ts
• Utilities: RxJS streams drive webhook event fan-out. Prefer existing helpers in src/utils and src/core/utils

Key Paths

• src/main.ts: runtime entry point; dynamically loads AppModule (Core vs Plus)
• src/api/**: REST controllers and WebSocket gateway
• src/core/**: shared abstractions (config services, engine bootstrap, storage, session management)
• src/plus/**: multi-session orchestration, advanced media services, and external persistence layers
• src/structures/** and src/utils/**: DTOs, enums (event names follow domain.action), helper utilities

Coding Expectations

• Favor composability and long-lived solutions
• Reuse existing helpers (parseBool, DefaultMap, media factories) instead of reinventing logic
• Stick to NestJS patterns: inject dependencies through constructors, expose provider tokens from modules
• Logging goes through injected PinoLogger or helpers in src/utils/logging.ts
• Respect path aliases (@waha/...) defined in tsconfig.json
• Prefer named function declarations over const arrow functions
• Avoid naming unused variables with a leading underscore
• Do not write verbose ternaries; use idiomatic helpers like ?? (nullish coalescing)
• Do not place await or other async calls inside ternary expressions (?:); use explicit if/else blocks
• For configs, prefer runtime configurability over constants (environment keys follow WAHA_* and WAHA_SESSION_CONFIG_*)

How to Run API

export DEBUG=1
export WAHA_API_KEY=666
export WAHA_DASHBOARD_PASSWORD=666
export WAHA_DASHBOARD_USERNAME=admin
export WWHATSAPP_SWAGGER_USERNAME=admin
export WHATSAPP_SWAGGER_PASSWORD=666
export WHATSAPP_DEFAULT_ENGINE={WEBJS|WPP|NOWEB|GOWS}
export WAHA_DEBUG_MODE=True
export WAHA_HTTP_STRICT_MODE=1
export WAHA_MEDIA_STORAGE=LOCAL
export WHATSAPP_FILES_FOLDER=./.media

npm run start

Code Guidelines

• Add @Activity() (from src/core/abc/activity.ts) to every engine method that makes a network call to WhatsApp servers
• It triggers maintainPresenceOnline() before the method runs, keeping the session ONLINE during API activity and scheduling an OFFLINE transition after an idle period
• Skip it on methods that only throw NotImplementedByEngineError / AvailableInPlusVersion

Related Sources

• WEBJS: ../whatsapp-web.js
• NOWEB: ../WhiskeySockets-Baileys and ../whatsapp-rust-bridge
• GOWS: ../gows and ../whatsmeow
• WPP: ../wa-js, ../wppconnect, ../wppconnect-server
• ChatWoot: ../chatwoot