96 lines
3.6 KiB
Markdown
96 lines
3.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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`
|