{"_id":"@buzzie-ai/whatsapp","_rev":"3-b277716fa67ed04ea3f5cf0bf269f645","name":"@buzzie-ai/whatsapp","dist-tags":{"latest":"1.0.2"},"versions":{"1.0.0":{"name":"@buzzie-ai/whatsapp","version":"1.0.0","_id":"@buzzie-ai/whatsapp@1.0.0","maintainers":[{"name":"buzzie","email":"arvind.raj.naidu@gmail.com"}],"bin":{"whatsapp":"bin/whatsapp.mjs"},"dist":{"shasum":"054a1a36a003f5986e43204d65af5117e82b7764","tarball":"https://registry.npmjs.org/@buzzie-ai/whatsapp/-/whatsapp-1.0.0.tgz","fileCount":34,"integrity":"sha512-8q/gy378lPSCLLUiK7DdXJEDRH0ruSkeMCdHlhsCJKZn9wKErdCs7qocEQQ+LCWPcI6RBvSDx7+2K/Tp6bjcYA==","signatures":[{"sig":"MEQCIFiMUGSMdLWv8yGNq9UNl+KbiFau2Iiv39a4AiG6DRvnAiBm6TZflbLD163qErXXYzmAnrCKivqWC5nwNUlfqUuPHQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":153774},"type":"module","gitHead":"f124da8be12d06cce23070e2e425c62a1ff6e3e0","scripts":{"start":"node bin/whatsapp.mjs"},"_npmUser":{"name":"buzzie","email":"arvind.raj.naidu@gmail.com"},"_npmVersion":"10.9.4","description":"WhatsApp CLI using Baileys protocol","directories":{},"_nodeVersion":"22.22.1","dependencies":{"zod":"^4.3.6","pino":"^9.5.0","chalk":"^5.3.0","openai":"^6.27.0","commander":"^12.1.0","videogaga":"^2.0.0","playwright":"^1.58.2","better-sqlite3":"^12.6.2","qrcode-terminal":"^0.12.0","@anthropic-ai/sdk":"^0.78.0","@whiskeysockets/baileys":"^6.7.16","@modelcontextprotocol/sdk":"^1.27.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/whatsapp_1.0.0_1774296588176_0.9417262861973872","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@buzzie-ai/whatsapp","version":"1.0.1","_id":"@buzzie-ai/whatsapp@1.0.1","maintainers":[{"name":"buzzie","email":"arvind.raj.naidu@gmail.com"}],"bin":{"whatsapp":"bin/whatsapp.mjs"},"dist":{"shasum":"709c1bd8cba369c32477f1888b2b6dcc0ee148c8","tarball":"https://registry.npmjs.org/@buzzie-ai/whatsapp/-/whatsapp-1.0.1.tgz","fileCount":34,"integrity":"sha512-9cwdhpcCBjALnT8sQ/3npTrgmc0J296a146Nn9iBZTHNLz9rN6ushP2uYxxknS+4orIA7MhiJLukwx4+RSvOfQ==","signatures":[{"sig":"MEUCICDVcRgC3zOZMddUF3MPRKLcPrg0vFEPbTpybVoB9DrbAiEAzizaaJGybrFSOCFtFCbWgI39pkFvr8Mof7QyrasfViU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":154084},"type":"module","gitHead":"e5ed8ed93958397fe9d555271495987cae16b740","scripts":{"start":"node bin/whatsapp.mjs"},"_npmUser":{"name":"buzzie","email":"arvind.raj.naidu@gmail.com"},"_npmVersion":"10.9.4","description":"WhatsApp CLI using Baileys protocol","directories":{},"_nodeVersion":"22.22.1","dependencies":{"zod":"^4.3.6","pino":"^9.5.0","chalk":"^5.3.0","openai":"^6.27.0","commander":"^12.1.0","videogaga":"^2.0.0","playwright":"^1.58.2","better-sqlite3":"^12.6.2","qrcode-terminal":"^0.12.0","@anthropic-ai/sdk":"^0.78.0","@whiskeysockets/baileys":"^6.7.16","@modelcontextprotocol/sdk":"^1.27.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/whatsapp_1.0.1_1774298807450_0.892378270982934","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@buzzie-ai/whatsapp","version":"1.0.2","description":"WhatsApp CLI using Baileys protocol","type":"module","bin":{"whatsapp":"bin/whatsapp.mjs"},"publishConfig":{"access":"public"},"scripts":{"start":"node bin/whatsapp.mjs"},"dependencies":{"@anthropic-ai/sdk":"^0.78.0","@modelcontextprotocol/sdk":"^1.27.1","@whiskeysockets/baileys":"^6.7.16","better-sqlite3":"^12.6.2","chalk":"^5.3.0","commander":"^12.1.0","openai":"^6.27.0","pino":"^9.5.0","playwright":"^1.58.2","qrcode-terminal":"^0.12.0","videogaga":"^2.0.0","zod":"^4.3.6"},"_id":"@buzzie-ai/whatsapp@1.0.2","gitHead":"25a5381ee8fce10e9c3766270929a11a5a7f831e","_nodeVersion":"22.22.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-nCXsk3CZJTATgxTgdd5ivgsDc7eAwgZ6SKH6p+kJq3ACqrSgbcS2Qi9ECmWPM4cvOmiVFObP+2VjPwMKMQxevg==","shasum":"d89f6a30865ca810f05c991dc0f6e64bd78c74ee","tarball":"https://registry.npmjs.org/@buzzie-ai/whatsapp/-/whatsapp-1.0.2.tgz","fileCount":34,"unpackedSize":154795,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDxL0CxT12c00HMl4UXYTaVFXKjZPcDG5jRtACvSYtmxAIgE7/bcO+F5AM11g7ttmPPAQXG0bEvK1mK/vkqY5/8oPg="}]},"_npmUser":{"name":"buzzie","email":"arvind.raj.naidu@gmail.com"},"directories":{},"maintainers":[{"name":"buzzie","email":"arvind.raj.naidu@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/whatsapp_1.0.2_1774305291127_0.49222083856597765"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-23T20:09:48.080Z","modified":"2026-03-23T22:34:51.444Z","1.0.0":"2026-03-23T20:09:48.319Z","1.0.1":"2026-03-23T20:46:47.616Z","1.0.2":"2026-03-23T22:34:51.298Z"},"description":"WhatsApp CLI using Baileys protocol","maintainers":[{"name":"buzzie","email":"arvind.raj.naidu@gmail.com"}],"readme":"# WhatsApp CLI\n\nA command-line tool and agentic bot for WhatsApp, built on the [Baileys](https://github.com/WhiskeySockets/Baileys) protocol library.\n\nSend messages, read chats, and run an AI-powered bot that responds to your self-chat messages — all from the terminal.\n\n## Features\n\n- **CLI commands** — send messages, list chats, read message history, send images and polls\n- **Agentic bot** — message yourself on WhatsApp and an LLM-powered assistant responds, with tools to search groups, summarize conversations, extract links, and create video digests\n- **MCP server** — expose WhatsApp as tools over stdio for AI integrations (Claude Desktop, etc.)\n- **Dual LLM support** — works with Anthropic Claude or OpenAI GPT\n- **Docker-ready** — pre-built multi-arch images on GHCR, or build locally\n\n## Quick start\n\n### With npm\n\n```bash\nnpx @buzzie-ai/whatsapp            # Run directly\n# or\nnpm install -g @buzzie-ai/whatsapp  # Install globally\nwhatsapp                            # First run walks you through setup\n```\n\n### With Docker (recommended for servers)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/arvindrajnaidu/whatsapp-cli/main/docker-setup.sh | bash\n```\n\nOr step by step:\n\n```bash\n# Pull and start\ndocker compose up -d\n\n# Link your WhatsApp account (use pairing code for headless servers)\ndocker compose exec whatsapp-bot node bin/whatsapp.mjs login --pairing-code 60123456789\n\n# Enter the 8-digit code on your phone — done\n```\n\n### From source\n\n```bash\ngit clone https://github.com/arvindrajnaidu/whatsapp-cli.git\ncd whatsapp-cli\nnpm install\n\n# First run walks you through login + LLM setup\nnpm start\n```\n\n## Usage\n\n### Bot mode (default)\n\n```bash\nnpm start\n# or\nnode bin/whatsapp.mjs\n```\n\nOn first run, a setup wizard walks you through QR code authentication and LLM API key configuration. After that, the bot connects and listens for messages you send to yourself on WhatsApp.\n\n**What the bot can do:**\n\n| Tool | Description |\n|------|-------------|\n| `list_groups` | List all your WhatsApp groups |\n| `search_groups` | Fuzzy search groups by name |\n| `read_messages` | Read recent messages from a group |\n| `search_messages` | Search messages across all chats |\n| `extract_links` | Find URLs shared in a group, categorized by platform |\n| `create_video_digest` | Download shared videos (Reels, Shorts, TikToks) and combine into one clip |\n\nExample self-chat messages:\n\n> \"Summarize what happened in Family Group today\"\n>\n> \"Find all YouTube links shared in Tech News this week\"\n>\n> \"Create a video digest from Memes Group\"\n\n### CLI commands\n\n```bash\nwhatsapp login                           # Link via QR code\nwhatsapp login --pairing-code <phone>    # Link via 8-digit pairing code\nwhatsapp logout                          # Unlink and clear credentials\nwhatsapp status                          # Show connection status\nwhatsapp chats                           # List recent chats\nwhatsapp messages <chat-id>              # Read messages from a chat\nwhatsapp send <phone-or-jid> <message>   # Send a text message\nwhatsapp send-image <phone-or-jid> <file> # Send an image\nwhatsapp send-poll <phone-or-jid> <question> # Send a poll\nwhatsapp listen                          # Stream incoming messages\nwhatsapp mcp                             # Start MCP server over stdio\n```\n\n### MCP server\n\nThe MCP server exposes WhatsApp tools over stdio, compatible with Claude Desktop and other MCP clients.\n\n```bash\nnode bin/whatsapp.mjs mcp\n```\n\n**MCP tools:** `send_message`, `list_chats`, `get_messages`, `search_chats`, `get_group_info`\n\nClaude Desktop config (`claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"whatsapp\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/whatsapp-cli/bin/whatsapp.mjs\", \"mcp\"]\n    }\n  }\n}\n```\n\n## Configuration\n\n### Environment variables\n\n| Variable | Description |\n|----------|-------------|\n| `ANTHROPIC_API_KEY` | Anthropic API key (for Claude) |\n| `OPENAI_API_KEY` | OpenAI API key (for GPT) |\n| `WHATSAPP_CLI_HOME` | Override config/auth directory (default: `~/.whatsapp-cli`) |\n\n### Config file\n\nThe setup wizard writes to `~/.whatsapp-cli/config.json`:\n\n```json\n{\n  \"llmProvider\": \"anthropic\",\n  \"llmKey\": \"sk-...\",\n  \"setupComplete\": true\n}\n```\n\nEnvironment variables take precedence over the config file.\n\n## Docker\n\n### Pre-built image\n\nMulti-arch images (amd64 + arm64) are published to GHCR on every push to `main`:\n\n```bash\ndocker pull ghcr.io/arvindrajnaidu/whatsapp-cli:latest\n```\n\n### docker-compose.yml\n\n```bash\n# Use the pre-built image\ndocker compose up -d\n\n# Or build locally\nWHATSAPP_IMAGE=whatsapp-cli:local docker compose up --build\n```\n\nCreate a `.env` file:\n\n```\nANTHROPIC_API_KEY=sk-ant-...\nOPENAI_API_KEY=sk-...\n```\n\nAuth credentials are persisted in the `whatsapp_data` Docker volume.\n\n### Common Docker commands\n\n```bash\n# Link WhatsApp via QR code (interactive — needs a terminal)\ndocker compose run --rm whatsapp-bot node bin/whatsapp.mjs login\n\n# Link via pairing code (headless servers)\ndocker compose run --rm whatsapp-bot node bin/whatsapp.mjs login --pairing-code 60123456789\n\n# Unlink WhatsApp\ndocker compose run --rm whatsapp-bot node bin/whatsapp.mjs logout\n\n# View live logs\ndocker compose logs -f\n\n# Restart the bot (e.g. after pulling a new image)\ndocker compose pull && docker compose up -d\n\n# Stop the bot\ndocker compose down\n\n# Open a shell inside the container\ndocker compose exec whatsapp-bot sh\n```\n\n### Deploy to a GCP Compute Engine instance\n\n```bash\n# SSH into the instance\ngcloud compute ssh <instance-name> --zone <zone> --project <project-id>\n\n# Install Docker\nsudo apt-get update && sudo apt-get install -y ca-certificates curl gnupg\nsudo install -m 0755 -d /etc/apt/keyrings\ncurl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg\necho \"deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian bookworm stable\" | sudo tee /etc/apt/sources.list.d/docker.list\nsudo apt-get update && sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin\n\n# Create project directory\nmkdir -p ~/whatsapp-bot && cd ~/whatsapp-bot\n\n# Create docker-compose.yml and .env (add your API key)\ncat > docker-compose.yml <<'EOF'\nservices:\n  whatsapp-bot:\n    image: ghcr.io/arvindrajnaidu/whatsapp-cli:latest\n    environment:\n      WHATSAPP_CLI_HOME: /data\n      OPENAI_API_KEY: ${OPENAI_API_KEY:-}\n      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}\n    volumes:\n      - whatsapp_data:/data\n    init: true\n    restart: unless-stopped\n\nvolumes:\n  whatsapp_data:\nEOF\n\necho \"OPENAI_API_KEY=sk-...\" > .env\n\n# Authenticate with GHCR (if the image is private)\necho \"<github-token>\" | sudo docker login ghcr.io -u <github-username> --password-stdin\n\n# Pull and start\nsudo docker compose pull && sudo docker compose up -d\n\n# Link WhatsApp (scan the QR code)\nsudo docker compose run --rm whatsapp-bot node bin/whatsapp.mjs login\n\n# Verify it's running\nsudo docker compose logs -f\n```\n\n## Integrating a Custom Backend\n\nWhatsApp-CLI is a **communication layer** — it handles WhatsApp connectivity, message routing, conversation history, and delivery. Business logic (LLM calls, CRM lookups, custom workflows) lives in a separate **backend**.\n\nBy default, the built-in backend handles everything (LLM + tools). You can replace it with your own backend to plug in any logic you want.\n\n### Backend interface\n\nYour backend receives a JSON request and returns a JSON response.\n\n**Request** (what your backend receives):\n\n```json\n{\n  \"type\": \"self_chat\",\n  \"jid\": \"6281234@s.whatsapp.net\",\n  \"groupName\": \"Sales Team\",\n  \"persona\": \"You are a sales assistant...\",\n  \"senderName\": \"Alice\",\n  \"history\": [\n    { \"role\": \"user\", \"content\": \"Alice: What's the status of the Acme deal?\" },\n    { \"role\": \"assistant\", \"content\": \"The Acme deal is in stage 3...\" }\n  ],\n  \"quotedContext\": null,\n  \"meta\": {\n    \"selfJid\": \"6281234@s.whatsapp.net\",\n    \"timestamp\": \"2026-03-23T10:00:00Z\"\n  }\n}\n```\n\n- `type` — `\"self_chat\"`, `\"group\"`, or `\"dm\"`\n- `history` — recent conversation messages in `[{role, content}]` format\n- `quotedContext` — text of the quoted message if this is a reply, or `null`\n\n**Response** (what your backend returns):\n\n```json\n{\n  \"text\": \"The Acme deal is in stage 3, expected close next week.\",\n  \"actions\": [\n    { \"type\": \"send_message\", \"jid\": \"120363xxx@g.us\", \"text\": \"Deal update posted.\" }\n  ]\n}\n```\n\nBoth `text` and `actions` are optional. `text` is sent as the bot's reply. `actions` trigger side-effects.\n\n### Supported action types\n\n| Action | Fields | Description |\n|--------|--------|-------------|\n| `reply_text` | `text` | Send a text reply to the current chat |\n| `send_message` | `jid`, `text` | Send a text message to any chat |\n| `react` | `emoji` | React to the triggering message |\n\n### Configuration\n\nAdd a `backend` key to `~/.whatsapp-cli/config.json`:\n\n**Built-in (default)** — no config needed:\n\n```json\n{ \"backend\": { \"type\": \"builtin\" } }\n```\n\n**HTTP backend** — POST conversation to an endpoint:\n\n```json\n{\n  \"backend\": {\n    \"type\": \"http\",\n    \"url\": \"https://my-bot.example.com/chat\",\n    \"headers\": { \"Authorization\": \"Bearer ${MY_BOT_TOKEN}\" },\n    \"timeout\": 30000\n  }\n}\n```\n\nHeader values support `${ENV_VAR}` interpolation.\n\n**Per-group overrides** (planned):\n\n```json\n{\n  \"backend\": { \"type\": \"builtin\" },\n  \"groupBackends\": {\n    \"120363xxx@g.us\": {\n      \"type\": \"http\",\n      \"url\": \"https://crm-bot.example.com/chat\"\n    }\n  }\n}\n```\n\n### Example: Building an HTTP backend\n\nA minimal Express server that echoes messages:\n\n```js\nimport express from \"express\";\nconst app = express();\napp.use(express.json());\n\napp.post(\"/chat\", (req, res) => {\n  const { history, senderName, groupName } = req.body;\n  const lastMessage = history[history.length - 1]?.content || \"\";\n  res.json({\n    text: `Got it, ${senderName}! You said: \"${lastMessage}\"`,\n  });\n});\n\napp.listen(3000, () => console.log(\"Backend listening on :3000\"));\n```\n\n## Architecture\n\n- **ESM-only** (`\"type\": \"module\"`)\n- **Entry:** `bin/whatsapp.mjs` -> `src/cli.js` (Commander) -> subcommands\n- **Session:** `src/session.js` manages the Baileys socket lifecycle, auth stored in `~/.whatsapp-cli/auth/`\n- **Bot:** `src/bot/` — NLU layer with conversation history, dual-provider LLM client (raw `fetch`, no SDK), tool definitions in provider-agnostic schema\n- **Backend:** `src/bot/backend.js` — pluggable backend dispatcher (built-in, HTTP, or custom)\n- **MCP:** `src/commands/mcp.js` — separate MCP server using `@modelcontextprotocol/sdk`\n\n## License\n\nMIT\n","readmeFilename":"README.md"}