AGENTS.md · devlikeapro/waha

Sections

1. Product & Variants
2. Tech Stack
3. Key Paths
4. Coding Expectations
5. How to Run API
6. Code Guidelines
7. MCP Tools
8. Related Sources

First lines (shown under the repo's Apache-2.0 license)

# 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
- Always use explicit property names in object literals — never shorthand: write
  `{ key: value }`, not `{ value }` (even when the variable name matches the
  key)
- Do not write verbose ternaries; use idiomatic helpers like `??` (nullish
  coalescing)
- Do not place `await` or other async calls inside ternary expressions (`?:`) or
  nullish-coalescing expressions (`??`); use explicit `if/else` blocks or assign
  the awaited value to a variable first
- For configs, prefer runtime configurability over constants (environment keys
  follow `WAHA_*` and `WAHA_SESSION_CONFIG_*`)
- Do not use decorative comment blocks (lines of dashes/underscores with a
  label) such as `// ─────────── NAME ───────────`; use plain inline comments or
  no comment at all

## 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`

## Request Validation (DTOs)

- No global pipe: every new `@Body()` / `@Query()` endpoint declares
  `WAHAValidationPipe`
- Under whitelist every DTO field needs a class-validator decorator, otherwise
  it is dropped;
  - `@ApiProperty` and the `*Property()` helpers in
    `src/structures/properties.dto.ts` do not count
- Nested class fields need `@ValidateNested()` + `@Type()` or their rules never
  run;
  - `@ValidateNested()` without `@Type()` drops all nested keys the same way

```typescript
@Post('/send')
@UsePipes(new WAHAValidationPipe())
async send(@Body() request: SendRequest) {}

// BAD
class _SendRequest {
  @ChatIdProperty()
  chatId: string; // no validator => stripped by whitelist

  options?: Options; // no @ValidateNested => Options rules never run

  @ValidateNested()
  items: Item[]; // no @Type => nested keys dropped
}

// GOOD
class SendRequest {
  @ChatIdProperty()
  @IsString()
  chatId: string;

  @ValidateNested()
  @Type(() => Options)
  @IsOptional()
  options?: Options;

  @ValidateNested({ each: true })
  @Type(() => Item)
  @IsArray()
  items: Item[];
}
```

- Union file fields (`FileURL | FileContent`): copy `LinkPreviewData.image` in
  `src/structures/chatting.dto.ts` - `@ValidateNested()` + `@Transform` to the
  concrete class + `@IsFileType()`

## MCP Tools

MCP tools live in `src/apps/mcp/tools/` and expose the HTTP API to AI clients.
Each tool file mirrors an API domain (e.g. `chats.tools.ts` → chats endpoints).

**When you change an existing API endpoint:**

- Check the corresponding `*.tools.ts` file and update the tool's `inputSchema`,
  description, or behavior if the API signature changed.

**When you add a new API endpoint:**

- Ask the user whether an MCP tool is needed for the new endpoint before
  creating one.
- If yes, add the tool to the matching `*.tools.ts` file (or create a new file