{
  "markdown": "# claude-channel-whatsapp\n\nA WhatsApp channel plugin for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Bridges WhatsApp Web to Claude using the [Baileys](https://github.com/WhiskeySockets/Baileys) library and the MCP channel protocol, so people can message Claude on WhatsApp and get responses.\n\n## How it works\n\nThis plugin runs as an MCP server that:\n\n1. Connects to WhatsApp Web using multi-device credentials (no phone needed to stay online)\n2. Receives incoming WhatsApp messages and delivers them to Claude Code via channel notifications\n3. Exposes `reply`, `react`, and `download_attachment` tools so Claude can respond\n\nMessages are gated by access control -- nobody can talk to Claude unless you explicitly approve them.\n\n## Prerequisites\n\n- **[Bun](https://bun.sh/)** runtime (v1.0+)\n- **Claude Code** v2.1+ with channel support\n- **Claude Max or Pro subscription** (channels require these tiers)\n\n## Quick setup\n\n### 1. Install the plugin\n\n```bash\n# Clone to Claude's plugins directory\nmkdir -p ~/.claude/plugins\ncd ~/.claude/plugins\ngit clone https://github.com/PenguinMiaou/claude-channel-whatsapp.git whatsapp\ncd whatsapp\nbun install\n```\n\n### 2. Launch Claude Code with the plugin\n\nPlugins that provide channels require the development flag:\n\n```bash\nclaude --dangerously-load-development-channels\n```\n\nClaude Code will detect the plugin from `~/.claude/plugins/whatsapp/` and start the MCP server automatically.\n\n### 3. Check status\n\nIn Claude Code, run:\n\n```\n/whatsapp:configure\n```\n\nThis shows whether auth credentials exist and lists any allowed senders.\n\n### 4. Authenticate with WhatsApp\n\nIf you have no existing auth, you need to link your WhatsApp account. The plugin uses Baileys' multi-device auth -- you scan a QR code or use a pairing code, similar to WhatsApp Web.\n\nTo import auth from another Baileys-based setup, copy the auth files (creds.json and key files) into `~/.claude/channels/whatsapp/auth/`, or use:\n\n```\n/whatsapp:configure import\n```\n\nTo clear auth and start fresh:\n\n```\n/whatsapp:configure clear\n```\n\n### 5. Pair a sender\n\nOnce connected, have someone message you on WhatsApp. The plugin will reply with a pairing code. In Claude Code, approve it:\n\n```\n/whatsapp:access pair <code>\n```\n\nThat sender is now allowlisted and their messages will reach Claude.\n\n## Access control\n\nAccess is managed entirely through the `/whatsapp:access` skill. The plugin never auto-approves anyone.\n\n### DM policies\n\n| Policy | Behavior |\n|---|---|\n| `pairing` (default) | Unknown senders get a pairing code; approve in Claude Code |\n| `allowlist` | Only pre-approved numbers can message; unknowns are silently dropped |\n| `disabled` | All incoming messages are dropped |\n\n### Commands\n\n```\n/whatsapp:access                    # Show status\n/whatsapp:access pair <code>        # Approve a pairing\n/whatsapp:access deny <code>        # Reject a pairing\n/whatsapp:access allow <phone>      # Add a phone number (E.164 format: +1234567890)\n/whatsapp:access remove <phone>     # Remove a phone number\n/whatsapp:access policy <mode>      # Set DM policy\n/whatsapp:access set <key> <value>  # Set config (ackReaction, textChunkLimit, chunkMode)\n```\n\nAll state lives in `~/.claude/channels/whatsapp/access.json`.\n\n## Tools\n\nThe plugin exposes three MCP tools to Claude:\n\n### `reply`\nSend a text message and/or file attachments to a WhatsApp chat.\n- `chat_id` (required): JID from the inbound message\n- `text` (required): message text (markdown is converted to WhatsApp formatting)\n- `reply_to`: message ID to quote\n- `files`: array of absolute file paths to attach (images send as photos, others as documents; max 50MB each)\n\n### `react`\nAdd an emoji reaction to a message.\n- `chat_id`, `message_id`, `emoji` (all required)\n\n### `download_attachment`\nDownload a media attachment (voice, video, document, sticker) from a recent message. Returns a local file path.\n- `message_json` (required): the attachment message ID from inbound metadata\n\n## LID mapping\n\nWhatsApp has been migrating from phone-based JIDs (e.g. `60168816782@s.whatsapp.net`) to Linked IDs (LIDs, e.g. `84576647000082@lid`). Baileys stores reverse mappings in the auth directory, and the plugin loads these to resolve LIDs back to phone numbers for access control.\n\nIf you see a raw LID number in logs instead of a phone number, the mapping file has not been created yet. This usually resolves after the contact sends a few messages.\n\n## Directory structure\n\n```\n~/.claude/plugins/whatsapp/          # Plugin code (this repo)\n~/.claude/channels/whatsapp/         # Runtime state (not in repo)\n  access.json                        # Access control config\n  auth/                              # Baileys auth state (creds.json, keys)\n  inbox/                             # Downloaded media attachments\n  approved/                          # Temp files for pairing confirmations\n```\n\n## Configuration\n\n### Environment variables\n\n| Variable | Default | Description |\n|---|---|---|\n| `WHATSAPP_STATE_DIR` | `~/.claude/channels/whatsapp` | Override the runtime state directory |\n\n### Access config keys\n\nSet via `/whatsapp:access set <key> <value>`:\n\n| Key | Default | Description |\n|---|---|---|\n| `ackReaction` | (none) | Emoji to react with on receipt |\n| `textChunkLimit` | 4000 | Max characters per message chunk |\n| `chunkMode` | `length` | `length` (hard cut) or `newline` (break at paragraphs/lines) |\n\n## Security notes\n\n- **Auth credentials** in `~/.claude/channels/whatsapp/auth/` are your WhatsApp session. Protect them like passwords. The directory is created with `0700` permissions.\n- **Access control** is enforced server-side. Claude cannot approve pairings or modify the allowlist -- only the user can, via the `/whatsapp:access` skill in their terminal.\n- **Channel messages are untrusted input.** The plugin instructs Claude to never act on access-control requests that arrive via WhatsApp. This prevents prompt injection from granting access.\n- **File sending is restricted.** The plugin refuses to send files from the channel state directory (auth, config) to prevent credential exfiltration.\n- The `--dangerously-load-development-channels` flag is required because this is a community plugin, not an official Anthropic channel.\n\n## License\n\nMIT -- see [LICENSE](LICENSE).\n",
  "bytes": 6288,
  "sha": "bb82cd8ad769ec40d7f99cc373b30365276c60b168580b75fc93fc6c1022ae2f",
  "repo_slug": "penguinmiaou/claude-channel-whatsapp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_penguinmiaou_claude_channel_whatsapp_cla_bda617d5/readme"
}