{"owner":"devlikeapro","repo":"waha","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# WAHA Agent Playbook\n\nThis guide summarizes how to explore, modify, and validate the WhatsApp HTTP API\n(WAHA) codebase when assisting as an automation or coding agent.\n\n## Product & Variants\n\n- WAHA ships in **Core** and **Plus** editions\n- Core lives under `src/core` and supports the default session with minimal\n  media features\n- Plus extends core via `src/plus` to add multi-session orchestration, richer\n  media handling, and external storage integrations\n- Core code must remain free from Plus-only references (pre-commit hook rejects\n  \"plus\" in core files)\n- Commit subjects: changes that touch `src/plus` require `[PLUS] …` prefix;\n  everything else uses `[core] …`\n\n## Tech Stack\n\n- **Runtime**: Node.js 22.x, Yarn 3.6 (Berry)\n- **Framework**: NestJS v11 with dependency injection and modular controllers in\n  `src/api`\n- **Engines**: WhatsApp engines are abstracted (`WEBJS`, `GOWS`, `NOWEB`,\n  `WPP`). Core uses `SessionManagerCore`; Plus swaps to `SessionManagerPlus`\n  with extra storage backends (Mongo/Postgres/SQLite)\n- **ESM Bridge**: ESM-only dependencies (Baileys) load through\n  `src/vendor/esm.ts`\n- **Utilities**: RxJS streams drive webhook event fan-out. Prefer existing\n  helpers in `src/utils` and `src/core/utils`\n\n## Key Paths\n\n- `src/main.ts`: runtime entry point; dynamically loads AppModule (Core vs Plus)\n- `src/api/**`: REST controllers and WebSocket gateway\n- `src/core/**`: shared abstractions (config services, engine bootstrap,\n  storage, session management)\n- `src/plus/**`: multi-session orchestration, advanced media services, and\n  external persistence layers\n- `src/structures/**` and `src/utils/**`: DTOs, enums (event names follow\n  `domain.action`), helper utilities\n\n## Coding Expectations\n\n- Favor composability and long-lived solutions\n- Reuse existing helpers (`parseBool`, `DefaultMap`, media factories) instead of\n  reinventing logic\n- Stick to NestJS patterns: inject dependencies through constructors, expose\n  provider tokens from modules\n- Logging goes through injected `PinoLogger` or helpers in\n  `src/utils/logging.ts`\n- Respect path aliases (`@waha/...`) defined in `tsconfig.json`\n- Prefer named function declarations over `const` arrow functions\n- Avoid naming unused variables with a leading underscore\n- Always use explicit property names in object literals — never shorthand: write\n  `{ key: value }`, not `{ value }` (even when the variable name matches the\n  key)\n- Do not write verbose ternaries; use idiomatic helpers like `??` (nullish\n  coalescing)\n- Do not place `await` or other async calls inside ternary expressions (`?:`) or\n  nullish-coalescing expressions (`??`); use explicit `if/else` blocks or assign\n  the awaited value to a variable first\n- For configs, prefer runtime configurability over constants (environment keys\n  follow `WAHA_*` and `WAHA_SESSION_CONFIG_*`)\n- Do not use decorative comment blocks (lines of dashes/underscores with a\n  label) such as `// ─────────── NAME ───────────`; use plain inline comments or\n  no comment at all\n\n## How to Run API\n\n```bash\nexport DEBUG=1\nexport WAHA_API_KEY=666\nexport WAHA_DASHBOARD_PASSWORD=666\nexport WAHA_DASHBOARD_USERNAME=admin\nexport WWHATSAPP_SWAGGER_USERNAME=admin\nexport WHATSAPP_SWAGGER_PASSWORD=666\nexport WHATSAPP_DEFAULT_ENGINE={WEBJS|WPP|NOWEB|GOWS}\nexport WAHA_DEBUG_MODE=True\nexport WAHA_HTTP_STRICT_MODE=1\nexport WAHA_MEDIA_STORAGE=LOCAL\nexport WHATSAPP_FILES_FOLDER=./.media\n\nnpm run start\n```\n\n## Code Guidelines\n\n- Add `@Activity()` (from `src/core/abc/activity.ts`) to every engine method\n  that makes a network call to WhatsApp servers\n- It triggers `maintainPresenceOnline()` before the method runs, keeping the\n  session ONLINE during API activity and scheduling an OFFLINE transition after\n  an idle period\n- Skip it on methods that only throw `NotImplementedByEngineError` /\n  `AvailableInPlusVersion`\n\n## MCP Tools\n\nMCP tools live in `src/apps/mcp/tools/` and expose the HTTP API to AI clients.\nEach tool file mirrors an API domain (e.g. `chats.tools.ts` → chats endpoints).\n\n**When you change an existing API endpoint:**\n\n- Check the corresponding `*.tools.ts` file and update the tool's `inputSchema`,\n  description, or behavior if the API signature changed.\n\n**When you add a new API endpoint:**\n\n- Ask the user whether an MCP tool is needed for the new endpoint before\n  creating one.\n- If yes, add the tool to the matching `*.tools.ts` file (or create a new file\n  for a new domain).\n- Every `@Tool` decorator must include an `annotations` block with all three\n  fields:\n  ```typescript\n  annotations: {\n    readOnlyHint: true | false,   // true = no side effects (GET-style)\n    destructiveHint: true | false, // true = irreversible deletion/logout\n    idempotentHint: true | false,  // true = safe to repeat with same args\n  }\n  ```\n- Input schemas live in the matching `*.zod.ts` file.\n- Tools call the API via `this.textRequest({ method, url, ... })` inherited from\n  `McpController`.\n\n## Related Sources\n\n- WEBJS: `../whatsapp-web.js`\n- NOWEB: `../WhiskeySockets-Baileys` and `../whatsapp-rust-bridge`\n- GOWS: `../gows` and `../whatsmeow`\n- WPP: `../wa-js`, `../wppconnect`, `../wppconnect-server`\n- ChatWoot: `../chatwoot`\n"},"files":{"AGENTS.md":"# WAHA Agent Playbook\n\nThis guide summarizes how to explore, modify, and validate the WhatsApp HTTP API\n(WAHA) codebase when assisting as an automation or coding agent.\n\n## Product & Variants\n\n- WAHA ships in **Core** and **Plus** editions\n- Core lives under `src/core` and supports the default session with minimal\n  media features\n- Plus extends core via `src/plus` to add multi-session orchestration, richer\n  media handling, and external storage integrations\n- Core code must remain free from Plus-only references (pre-commit hook rejects\n  \"plus\" in core files)\n- Commit subjects: changes that touch `src/plus` require `[PLUS] …` prefix;\n  everything else uses `[core] …`\n\n## Tech Stack\n\n- **Runtime**: Node.js 22.x, Yarn 3.6 (Berry)\n- **Framework**: NestJS v11 with dependency injection and modular controllers in\n  `src/api`\n- **Engines**: WhatsApp engines are abstracted (`WEBJS`, `GOWS`, `NOWEB`,\n  `WPP`). Core uses `SessionManagerCore`; Plus swaps to `SessionManagerPlus`\n  with extra storage backends (Mongo/Postgres/SQLite)\n- **ESM Bridge**: ESM-only dependencies (Baileys) load through\n  `src/vendor/esm.ts`\n- **Utilities**: RxJS streams drive webhook event fan-out. Prefer existing\n  helpers in `src/utils` and `src/core/utils`\n\n## Key Paths\n\n- `src/main.ts`: runtime entry point; dynamically loads AppModule (Core vs Plus)\n- `src/api/**`: REST controllers and WebSocket gateway\n- `src/core/**`: shared abstractions (config services, engine bootstrap,\n  storage, session management)\n- `src/plus/**`: multi-session orchestration, advanced media services, and\n  external persistence layers\n- `src/structures/**` and `src/utils/**`: DTOs, enums (event names follow\n  `domain.action`), helper utilities\n\n## Coding Expectations\n\n- Favor composability and long-lived solutions\n- Reuse existing helpers (`parseBool`, `DefaultMap`, media factories) instead of\n  reinventing logic\n- Stick to NestJS patterns: inject dependencies through constructors, expose\n  provider tokens from modules\n- Logging goes through injected `PinoLogger` or helpers in\n  `src/utils/logging.ts`\n- Respect path aliases (`@waha/...`) defined in `tsconfig.json`\n- Prefer named function declarations over `const` arrow functions\n- Avoid naming unused variables with a leading underscore\n- Always use explicit property names in object literals — never shorthand: write\n  `{ key: value }`, not `{ value }` (even when the variable name matches the\n  key)\n- Do not write verbose ternaries; use idiomatic helpers like `??` (nullish\n  coalescing)\n- Do not place `await` or other async calls inside ternary expressions (`?:`) or\n  nullish-coalescing expressions (`??`); use explicit `if/else` blocks or assign\n  the awaited value to a variable first\n- For configs, prefer runtime configurability over constants (environment keys\n  follow `WAHA_*` and `WAHA_SESSION_CONFIG_*`)\n- Do not use decorative comment blocks (lines of dashes/underscores with a\n  label) such as `// ─────────── NAME ───────────`; use plain inline comments or\n  no comment at all\n\n## How to Run API\n\n```bash\nexport DEBUG=1\nexport WAHA_API_KEY=666\nexport WAHA_DASHBOARD_PASSWORD=666\nexport WAHA_DASHBOARD_USERNAME=admin\nexport WWHATSAPP_SWAGGER_USERNAME=admin\nexport WHATSAPP_SWAGGER_PASSWORD=666\nexport WHATSAPP_DEFAULT_ENGINE={WEBJS|WPP|NOWEB|GOWS}\nexport WAHA_DEBUG_MODE=True\nexport WAHA_HTTP_STRICT_MODE=1\nexport WAHA_MEDIA_STORAGE=LOCAL\nexport WHATSAPP_FILES_FOLDER=./.media\n\nnpm run start\n```\n\n## Code Guidelines\n\n- Add `@Activity()` (from `src/core/abc/activity.ts`) to every engine method\n  that makes a network call to WhatsApp servers\n- It triggers `maintainPresenceOnline()` before the method runs, keeping the\n  session ONLINE during API activity and scheduling an OFFLINE transition after\n  an idle period\n- Skip it on methods that only throw `NotImplementedByEngineError` /\n  `AvailableInPlusVersion`\n\n## MCP Tools\n\nMCP tools live in `src/apps/mcp/tools/` and expose the HTTP API to AI clients.\nEach tool file mirrors an API domain (e.g. `chats.tools.ts` → chats endpoints).\n\n**When you change an existing API endpoint:**\n\n- Check the corresponding `*.tools.ts` file and update the tool's `inputSchema`,\n  description, or behavior if the API signature changed.\n\n**When you add a new API endpoint:**\n\n- Ask the user whether an MCP tool is needed for the new endpoint before\n  creating one.\n- If yes, add the tool to the matching `*.tools.ts` file (or create a new file\n  for a new domain).\n- Every `@Tool` decorator must include an `annotations` block with all three\n  fields:\n  ```typescript\n  annotations: {\n    readOnlyHint: true | false,   // true = no side effects (GET-style)\n    destructiveHint: true | false, // true = irreversible deletion/logout\n    idempotentHint: true | false,  // true = safe to repeat with same args\n  }\n  ```\n- Input schemas live in the matching `*.zod.ts` file.\n- Tools call the API via `this.textRequest({ method, url, ... })` inherited from\n  `McpController`.\n\n## Related Sources\n\n- WEBJS: `../whatsapp-web.js`\n- NOWEB: `../WhiskeySockets-Baileys` and `../whatsapp-rust-bridge`\n- GOWS: `../gows` and `../whatsmeow`\n- WPP: `../wa-js`, `../wppconnect`, `../wppconnect-server`\n- ChatWoot: `../chatwoot`\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# WAHA Agent Playbook\n\nThis guide summarizes how to explore, modify, and validate the WhatsApp HTTP API\n(WAHA) codebase when assisting as an automation or coding agent.\n\n## Product & Variants\n\n- WAHA ships in **Core** and **Plus** editions\n- Core lives under `src/core` and supports the default session with minimal\n  media features\n- Plus extends core via `src/plus` to add multi-session orchestration, richer\n  media handling, and external storage integrations\n- Core code must remain free from Plus-only references (pre-commit hook rejects\n  \"plus\" in core files)\n- Commit subjects: changes that touch `src/plus` require `[PLUS] …` prefix;\n  everything else uses `[core] …`\n\n## Tech Stack\n\n- **Runtime**: Node.js 22.x, Yarn 3.6 (Berry)\n- **Framework**: NestJS v11 with dependency injection and modular controllers in\n  `src/api`\n- **Engines**: WhatsApp engines are abstracted (`WEBJS`, `GOWS`, `NOWEB`,\n  `WPP`). Core uses `SessionManagerCore`; Plus swaps to `SessionManagerPlus`\n  with extra storage backends (Mongo/Postgres/SQLite)\n- **ESM Bridge**: ESM-only dependencies (Baileys) load through\n  `src/vendor/esm.ts`\n- **Utilities**: RxJS streams drive webhook event fan-out. Prefer existing\n  helpers in `src/utils` and `src/core/utils`\n\n## Key Paths\n\n- `src/main.ts`: runtime entry point; dynamically loads AppModule (Core vs Plus)\n- `src/api/**`: REST controllers and WebSocket gateway\n- `src/core/**`: shared abstractions (config services, engine bootstrap,\n  storage, session management)\n- `src/plus/**`: multi-session orchestration, advanced media services, and\n  external persistence layers\n- `src/structures/**` and `src/utils/**`: DTOs, enums (event names follow\n  `domain.action`), helper utilities\n\n## Coding Expectations\n\n- Favor composability and long-lived solutions\n- Reuse existing helpers (`parseBool`, `DefaultMap`, media factories) instead of\n  reinventing logic\n- Stick to NestJS patterns: inject dependencies through constructors, expose\n  provider tokens from modules\n- Logging goes through injected `PinoLogger` or helpers in\n  `src/utils/logging.ts`\n- Respect path aliases (`@waha/...`) defined in `tsconfig.json`\n- Prefer named function declarations over `const` arrow functions\n- Avoid naming unused variables with a leading underscore\n- Always use explicit property names in object literals — never shorthand: write\n  `{ key: value }`, not `{ value }` (even when the variable name matches the\n  key)\n- Do not write verbose ternaries; use idiomatic helpers like `??` (nullish\n  coalescing)\n- Do not place `await` or other async calls inside ternary expressions (`?:`) or\n  nullish-coalescing expressions (`??`); use explicit `if/else` blocks or assign\n  the awaited value to a variable first\n- For configs, prefer runtime configurability over constants (environment keys\n  follow `WAHA_*` and `WAHA_SESSION_CONFIG_*`)\n- Do not use decorative comment blocks (lines of dashes/underscores with a\n  label) such as `// ─────────── NAME ───────────`; use plain inline comments or\n  no comment at all\n\n## How to Run API\n\n```bash\nexport DEBUG=1\nexport WAHA_API_KEY=666\nexport WAHA_DASHBOARD_PASSWORD=666\nexport WAHA_DASHBOARD_USERNAME=admin\nexport WWHATSAPP_SWAGGER_USERNAME=admin\nexport WHATSAPP_SWAGGER_PASSWORD=666\nexport WHATSAPP_DEFAULT_ENGINE={WEBJS|WPP|NOWEB|GOWS}\nexport WAHA_DEBUG_MODE=True\nexport WAHA_HTTP_STRICT_MODE=1\nexport WAHA_MEDIA_STORAGE=LOCAL\nexport WHATSAPP_FILES_FOLDER=./.media\n\nnpm run start\n```\n\n## Code Guidelines\n\n- Add `@Activity()` (from `src/core/abc/activity.ts`) to every engine method\n  that makes a network call to WhatsApp servers\n- It triggers `maintainPresenceOnline()` before the method runs, keeping the\n  session ONLINE during API activity and scheduling an OFFLINE transition after\n  an idle period\n- Skip it on methods that only throw `NotImplementedByEngineError` /\n  `AvailableInPlusVersion`\n\n## MCP Tools\n\nMCP tools live in `src/apps/mcp/tools/` and expose the HTTP API to AI clients.\nEach tool file mirrors an API domain (e.g. `chats.tools.ts` → chats endpoints).\n\n**When you change an existing API endpoint:**\n\n- Check the corresponding `*.tools.ts` file and update the tool's `inputSchema`,\n  description, or behavior if the API signature changed.\n\n**When you add a new API endpoint:**\n\n- Ask the user whether an MCP tool is needed for the new endpoint before\n  creating one.\n- If yes, add the tool to the matching `*.tools.ts` file (or create a new file\n  for a new domain).\n- Every `@Tool` decorator must include an `annotations` block with all three\n  fields:\n  ```typescript\n  annotations: {\n    readOnlyHint: true | false,   // true = no side effects (GET-style)\n    destructiveHint: true | false, // true = irreversible deletion/logout\n    idempotentHint: true | false,  // true = safe to repeat with same args\n  }\n  ```\n- Input schemas live in the matching `*.zod.ts` file.\n- Tools call the API via `this.textRequest({ method, url, ... })` inherited from\n  `McpController`.\n\n## Related Sources\n\n- WEBJS: `../whatsapp-web.js`\n- NOWEB: `../WhiskeySockets-Baileys` and `../whatsapp-rust-bridge`\n- GOWS: `../gows` and `../whatsmeow`\n- WPP: `../wa-js`, `../wppconnect`, `../wppconnect-server`\n- ChatWoot: `../chatwoot`\n","category":"root","tokens":1298}]}