---
name: whatsapp-ai-bot
description: Build complete WhatsApp AI bot applications with Express, Socket.IO, whatsapp-web.js, Google Gemini AI, SQLite, and React dashboard. Use this skill when the user wants to create a new WhatsApp bot, WhatsApp automation, WhatsApp + AI integration, or any app that receives messages on WhatsApp and processes them with AI. Also triggers for adding WhatsApp functionality to existing projects, building chatbots, or creating AI-powered WhatsApp services. Generates full-stack projects with backend (Express + WhatsApp + AI), admin dashboard (React + Vite + Tailwind), and deployment configs (PM2 + Nginx).
---

# WhatsApp AI Bot Builder

Battle-tested architecture extracted from LuxStudio WhatsApp (production app generating AI photos via WhatsApp). This skill scaffolds and guides building any WhatsApp + AI application.

## Workflow

### 1. Understand Requirements

Before scaffolding, clarify with the user:
- **AI task**: What does the bot do? (generate images, answer questions, transcribe audio, etc.)
- **AI provider**: Gemini (default), OpenAI, Claude, or other
- **Conversation flow**: What states does the user go through?
- **Dashboard needs**: Admin panel required? What metrics to track?
- **Deployment target**: VPS details (IP, domain, port)

### 2. Scaffold Project

Run the scaffold script to generate the full project structure:

```bash
bash ~/.claude/skills/whatsapp-ai-bot/scripts/scaffold.sh <project-name> <port>
```

This creates the complete project with all template files. Then customize for the specific use case.

### 3. Customize the Bot

After scaffolding, adapt these files to the specific use case:

| File | What to customize |
|------|-------------------|
| `backend/src/bot.js` | Conversation states + flow logic |
| `backend/src/ai-service.js` | AI provider + prompts |
| `backend/src/database.js` | Tables for your domain data |
| `backend/src/api.js` | Dashboard API endpoints |
| `dashboard/src/pages/` | Dashboard pages |

### 4. Deploy

Follow the deploy checklist in [references/deploy-checklist.md](references/deploy-checklist.md).

## Architecture Overview

```
User (WhatsApp) → whatsapp-web.js (Puppeteer) → Express Server
                                                      ↓
                                               Bot State Machine
                                                      ↓
                                               AI Service (Gemini/OpenAI/Claude)
                                                      ↓
                                               Response → WhatsApp
                                                      ↓
                                               SQLite (logs, sessions, stats)
                                                      ↓
                                               Socket.IO → React Dashboard
```

### Critical Rules (NEVER skip these)

1. **`express.json({ limit: '50mb' })`** — images/audio as base64 are large
2. **`--no-sandbox` in Puppeteer** — mandatory on Linux VPS
3. **`LocalAuth` for session persistence** — stored in `.wwebjs_auth/`
4. **Filter groups**: `if (chat.isGroup || message.from === 'status@broadcast') return`
5. **SQLite WAL mode**: `db.pragma('journal_mode = WAL')` — concurrent reads
6. **Nginx WebSocket headers**: `Upgrade` + `Connection "upgrade"` — Socket.IO needs this
7. **Retry with backoff** for AI APIs — they return 503 frequently
8. **Stop on 429/quota** — don't burn retries when rate-limited
9. **`type: "module"` in package.json** — ES modules (import/export)
10. **Base64 data URI format**: `data:image/jpeg;base64,AAAA...` for DB storage

## Reference Files

- **[Architecture deep-dive](references/architecture.md)**: Server setup, Socket.IO, middleware, SPA serving
- **[WhatsApp client](references/whatsapp-setup.md)**: Connection, QR, events, media handling, message types
- **[State machine patterns](references/state-machine.md)**: FSM design, session memory, rate limiting, audio/image handling
- **[AI integration](references/ai-integration.md)**: Gemini/OpenAI setup, prompts, retry logic, streaming
- **[Database schema](references/database-schema.md)**: SQLite tables, indexes, settings, daily stats
- **[Dashboard](references/dashboard.md)**: React pages, Socket.IO client, real-time updates
- **[Deploy checklist](references/deploy-checklist.md)**: PM2, Nginx, SSL, troubleshooting

## Template Files

All template source files are in `assets/templates/`. The scaffold script copies and configures them automatically.
