This is a long-running backend service that connects to WhatsApp Web (Baileys), calls the LLM, and sends replies back to WhatsApp chats.

Follow the steps in order. No coding is required. Commands are run from the project root unless noted.

• Install Node.js 20+ (verify with node -v and npm -v).
• Keep your WhatsApp account available on your phone (you will scan a QR code later).

cd gateway

This service reads from gateway/.env by default. Create it first:

cp .env.example .env

Then open gateway/.env and paste your team secrets from your password manager:

• Team shared link (internal only): <your-shared-secret-link>
• Required at minimum: GEMINI_API_KEY=your_key
• If your secret manager provides full KEY=VALUE lines, paste them directly into gateway/.env and save.

npm install

npm run dev

On first run, the terminal will show a QR code. In WhatsApp, open Linked Devices and scan it.

Open a new terminal and run:

curl http://localhost:3001/healthz

If you get a JSON response (for example with connection status fields), the service is running.

In the terminal running npm run dev, press Ctrl + C.

If you are on Windows, open PowerShell at the project root and run:

cd .\gateway
Copy-Item .env.example .env
notepad .env

Paste your environment variables from your password manager into gateway\.env, save, then continue:

npm install
npm run dev

Open a second PowerShell window to check health:

Invoke-RestMethod http://localhost:3001/healthz

• GEMINI_API_URL: Override Gemini API base URL (for proxies/custom gateways).
• GEMINI_MODEL: Override Gemini model ID (default: gemini-2.5-flash).
• INBOUND_DEBOUNCE_MS: Debounce window (ms) for batching consecutive messages from the same sender. 0 disables debounce.
• WHATSAPP_DISABLE_PROXY: Set to true to force WhatsApp connection/media requests to bypass system proxy.
• WHATSAPP_PROXY_URL: Dedicated proxy for WhatsApp only (higher priority than system HTTP(S)_PROXY).
• MCP_MAX_ROUNDS: Max MCP tool rounds per user request (default 20).
• MCP_MAX_CALLS_PER_ROUND: Max tool calls per round (default 4).
• MCP_MAX_TOOL_RETRIES: Max retries for retryable tool failures (default 2).
• MCP_TOOL_RETRY_DELAY_MS: Base delay for tool retries (default 800ms).
• MCP_FINAL_ANSWER_ON_LIMIT: If tool round limit is hit, force model to produce a final answer (default true).
• MCP_ALLOW_RAW_TOOL_REQUEST: If limit is hit and model still returns tool requests, allow raw passthrough (default true).
• Skills directory: gateway/skills/ (read SKILL.md files on demand through read tools).
• Map tools (real-time POI/routes):
  • GOOGLE_MAPS_API_KEY: Enable Google Geocoding / Places / Directions tools.
  • GOOGLE_ROUTES_API_URL: Optional override for Google Routes API base URL.
  • MAPBOX_ACCESS_TOKEN: Enable Mapbox Isochrone tool.
  • Security note: map capabilities run through an internal MCP-style registry on the server, with no public HTTP endpoints and no direct network access granted to the LLM.

• Error Missing required env var: GEMINI_API_KEY: your gateway/.env is incomplete. Re-paste and save your env variables.
• Port already in use: change PORT=3001 in gateway/.env to another port (for example PORT=3011), then restart.

• Bot switch (recommended):
  • /bot on: enable auto-reply in current chat
  • /bot off: disable auto-reply in current chat
  • /bot status: check current chat switch state
• Bot switch (short form):
  • /on: enable
  • /off: disable
• Backward-compatible commands:
  • /gateway start
  • /gateway stop
  • /gateway status
• Session reset:
  • /reset or /new: reset current chat context
• Group events (group chats only):
  • Direct natural-language creation (recommended):
    • Create a group event Weekly Sync tomorrow 19:30 to 20:30 routine sync
    • Help me create an event: Saturday 19:30 start, end 21:00
    • Create event Name: Weekly Sync Start: 2026-02-10 19:30 End: 2026-02-10 20:30 Description: routine sync
  • Legacy format compatibility:
    • /event: show event creation usage
    • /event {"name":"Weekly Sync","start":"2026-02-10 19:30","end":"2026-02-10 20:30","description":"routine sync"}
    • /event Weekly Sync | 2026-02-10 19:30 | 2026-02-10 20:30 | routine sync

• GET /healthz: returns basic status (WhatsApp connection, queue size, switch statistics, etc.).