With Anthropic's recent policy changes, many users lost access to their AI agents through messaging platforms. While official channel plugins exist for Telegram and Instagram, WhatsApp — the world's most used messaging app — had no solution.
This plugin fills that gap. It connects your WhatsApp number directly to Claude Code, turning it into a fully functional AI agent that responds through WhatsApp.
WhatsApp channel plugin for Claude Code — connect your WhatsApp to an AI agent. QR scan, voice transcription, access control, media support.
Native WhatsApp channel — scan a QR (or use a pairing code on headless servers), pair your contacts, start chatting with Claude.
Access control — pairing codes, allowlist, group gating with requireMention, plus per-chat history scope (each chat sees its own history by default; designated owners read all). Nobody talks to your agent without permission, and no chat reads another's history.
Permission relay — when Claude wants to run a tool, get the prompt on WhatsApp; approve or deny with a 👍 reaction or yes <id> reply.
Local search, export, and discovery — every message indexed locally; full-text search, contact and chat discovery, message-context lookup, request older messages from WhatsApp, dump chats to markdown / jsonl / csv.
Voice transcription — local Whisper by default (no API keys, 99+ languages); optional cloud providers (Groq / OpenAI) for higher quality on slower hardware.
Media pipeline — inbound images, audio, video, and documents auto-downloaded for Claude to read.
Reply shaping — paragraph-aware chunking, optional ack reaction, auto-document for long replies, message editing without push notifications.
Inbound debouncing — rapid-fire texts from the same sender are batched into a single agent turn, so Claude stops answering mid-thought when the user is still typing.
When prompted for scope, select "Install for you, in this repo only (local scope)" — this keeps the agent isolated to this folder.
3. Close and relaunch with the WhatsApp channel.
Exit Claude Code (/exit or Ctrl+C), then relaunch:
claude --dangerously-load-development-channels plugin:whatsapp@claude-whatsapp --dangerously-skip-permissions
--dangerously-skip-permissions lets the agent run without asking for confirmation on every action — recommended for a smooth experience. First launch installs dependencies in the background (~60-90s). Subsequent launches are instant.
4. Link your number.
/whatsapp:configure
Opens a QR code on your screen. Scan it with WhatsApp > Settings > Linked Devices > Link a Device.
Headless server / no camera? Run /whatsapp:configure pair +5491155556666 first. The next link cycle generates an 8-character code instead of a QR — read it from the terminal, then on your phone open WhatsApp > Linked Devices > Link with phone number and type it in.
Session is saved — you won't need to link again unless you log out.
5. Pair.
Message your WhatsApp number from another phone. It replies with a 6-character code. In Claude Code:
In-depth guides, each with worked examples end-to-end. The README is the at-a-glance reference; these pages are where the tutorials live.
Setup & access
docs/access.md — DM access tutorial: pairing flow, the three policies, JID formats, recovery.
docs/groups.md — adding the bot to a WhatsApp group, the four access policies, discovery flow, member discovery, edge cases.
Runtime reference
docs/configuration.md — every /whatsapp:configure sub-command (linking, audio, reply shaping, inbound debouncing, auth migration, reset) and every key in config.json.
docs/tools.md — per-tool reference (reply, react, search_messages, fetch_history, …) with natural-language examples and pitfalls.
docs/permission-relay.md — how Claude Code's permission prompts reach your phone, how to respond from text or reaction.
docs/media-voice.md — inbound media runtime: layout, the 50 MB cap, the inbox/ sandbox, voice transcription end-to-end, stickers / locations / contacts.
Default policy is pairing. IDs are WhatsApp JIDs — format depends on your Baileys version (e.g. [email protected] or 12345678901234@lid). Check /whatsapp:access to see the exact IDs.
Per-chat history scope. Nine read/exfil tools (search_messages, fetch_history, export_chat, list_group_senders, get_message_context, get_chat_analytics, list_chats, search_contact, forward_message) are gated by chat. Owners (ownerJids) read every indexed chat; non-owner chats are sandboxed to their own history by default. Override per-chat with set-scope. First pair after a fresh install seeds ownerJids automatically. Terminal operator can set WHATSAPP_OWNER_BYPASS=1 in the environment for full access without an inbound. Full model: docs/access.md#history-scope.
Group access is fully independent of DM access. Allowing someone in a group does NOT let them DM the bot, and pairing a DM contact does NOT auto-allow them in any group.
Command
Description
/whatsapp:access add-group <jid>
Allow a group, mention-only (default).
/whatsapp:access add-group <jid> --no-mention
Allow a group, open delivery (every message goes to Claude).
Reactions behave differently depending on what the user reacts to:
On a permission request (a 🔐 Claude wants to run … message): the plugin intercepts the reaction directly and converts it into an approve/deny decision sent back to Claude Code. The terminal prompt clears automatically.
Reaction
Meaning
👍 / ✅
Approve the pending tool
👎 / ❌
Deny the pending tool
Skin-tone variants of 👍 / 👎 also work. Pending requests time out after 5 minutes; the terminal-side dialog stays active either way, so you can also approve there.
On a regular message: the reaction is forwarded to Claude as [Reacted with X] and Claude interprets it from context — typically 👍 as "ok/proceed" and 👎 as "no/stop".
When Claude Code asks to run a tool (e.g. a Bash command), the plugin broadcasts the request to every allowlisted DM contact:
🔐 Claude wants to run *Bash*
ls -la /tmp
Reply *yes abcde* / *no abcde* or react 👍 / 👎.
Respond with text (yes <id> / no <id>, case-insensitive) or a reaction (👍 / ✅ to allow, 👎 / ❌ to deny). Whoever responds first wins; the terminal prompt remains active as a fallback. Pending requests expire after 5 minutes.
Every inbound and outbound message — including reactions, edits, file captions, and history backfills — is indexed locally to SQLite + FTS5. Claude can full-text search your chats, pull older messages from WhatsApp on demand, and export a chat as markdown / jsonl / csv. The store is local-only, user-only permissions (0600), and safe to delete to wipe history.
When a user fires several plain-text messages in quick succession ("hi" → "actually" → "can you…"), the plugin holds them in a 2-second sliding window per (chat, sender) and hands the whole batch to Claude as one agent turn — so Claude doesn't start answering the first message while the user is still composing. Attachments, voice notes, reactions, and permission replies bypass the buffer and flush any pending text first so ordering is preserved.
Tune via inboundDebounceMs in config.json (default 2000; set to 0 to disable and get the pre-1.12 one-message-one-turn behavior).
Inbound photos, voice messages, videos, and documents are automatically downloaded to <channel-dir>/inbox/ — <project>/.whatsapp/inbox/ for local-scope installs, ~/.claude/channels/whatsapp/inbox/ for the global fallback. Max 50 MB per inbound file. The file path is included in the notification so Claude can read or reference it.
Stickers, locations, and contacts are forwarded as descriptive text ([Sticker received], [Location: lat, lng], [Contact: name]) without downloading a file.
By default, voice messages arrive as [Voice message received] with the audio file saved. To enable automatic local transcription:
/whatsapp:configure audio
The Whisper model (~77MB for base) downloads on the first voice message and is cached permanently. Runs entirely on your machine — 99+ languages supported, no API keys needed. Recommended: set your primary language explicitly (/whatsapp:configure audio es) for short-message accuracy.
Cloud provider option (advanced): for higher-quality transcription on slower hardware, switch to Groq or OpenAI via /whatsapp:configure audio provider (requires GROQ_API_KEY or OPENAI_API_KEY env var). Local stays the default and recommendation; cloud failures fall back to local automatically. See docs/media-voice.md#voice-transcription-end-to-end for the trade-offs.
Once the agent is running, type /mcp inside Claude Code and enable computer use. This lets the agent control your computer (click, type, take screenshots) — useful for tasks that go beyond chat.
If your WhatsApp number already runs on another local Baileys-based tool — OpenClaw, wppconnect, or a previous checkout of this plugin — you have two paths:
Option A — Just switch at link time. Close the other tool (or stop that agent), scan the QR here, and the number will work through Claude Code natively. Each platform re-links the WhatsApp session on startup, so they don't conflict — just don't run both at the same time on the same number.
Option B — Import the session directly, with no re-scan:
Validates the source, backs up the current session to auth.backup-<timestamp>/, copies the credentials over, and tightens permissions. After import, /reload-plugins picks up the imported session.
Important: importing creds that are also in active use elsewhere will cause both sides to fight for the WhatsApp session. Stop the source app first.
To keep your WhatsApp agent running permanently, wrap Claude Code with your platform's process manager:
macOS (launchd) — create a com.whatsapp-agent.plist under ~/Library/LaunchAgents/ that runs claude --dangerously-load-development-channels plugin:whatsapp@claude-whatsapp --dangerously-skip-permissions with RunAtLoad and KeepAlive set.
Linux (systemd) — create ~/.config/systemd/user/whatsapp-agent.service with the same command; enable with systemctl --user enable --now whatsapp-agent.
Windows (Task Scheduler) — scheduled task that runs at login, with "Start in" set to your agent folder.
Install the plugin in each folder with local scope and scan a separate QR code for each. See docs/operations.md#multiple-agents--multiple-numbers for the caveats (one instance per number, single-instance lock).
This plugin is namespaced under its own plugin id (whatsapp) and its own MCP server name (whatsapp), so loading it together with other plugins does not collide on tool names, skill names, or hooks. Nothing here assumes any specific other plugin is installed.
Update:/plugin update whatsapp@claude-whatsapp, close Claude, relaunch, wait for the deps install notification (~60s on first update), then /reload-plugins. Your session / access / config / message history are preserved.
Uninstall:/plugin uninstall whatsapp@claude-whatsapp. The channel directory remains — delete <your-project>/.whatsapp/ (or ~/.claude/channels/whatsapp/) if you also want to wipe state.
Clear cache: close Claude, rm -rf ~/.claude/plugins/cache/claude-whatsapp, reopen and reinstall.
After /plugin update, the agent stops responding — The plugin is reinstalling its dependencies in the background. Wait, don't restart. Run /whatsapp:configure to see live status — it'll report deps_missing while the install runs and transition out automatically. Once out, /reload-plugins brings everything cleanly online.
Voice messages transcribe in the wrong language — Set your language explicitly: /whatsapp:configure audio es. Without it, the model often defaults to English on short clips.
QR code expired — Run /whatsapp:configure again. The server generates a fresh QR every ~20 seconds.
WhatsApp disconnected after a phone-side logout — Run /whatsapp:configure reset then /whatsapp:configure to scan a new QR.
Unofficial API — Baileys is not endorsed by WhatsApp. Use responsibly — no spam, no bulk messaging.
One linked device slot — Unlink anytime from WhatsApp > Settings > Linked Devices.
Local-only message history — Inbound and outbound messages (including reactions, edits, and history backfills) are indexed to a local SQLite store with FTS5; the search_messages, fetch_history, and export_chat tools sit on top. Nothing leaves your machine.
This project is not affiliated with, endorsed by, or associated with WhatsApp, Meta, or Anthropic. WhatsApp is a trademark of Meta Platforms, Inc. Claude is a trademark of Anthropic, PBC. This plugin uses the unofficial Baileys library for WhatsApp Web connectivity.
C
Claude Whatsapp
crisandrews·18 estrellas·
WhatsApp channel plugin for Claude Code — connect your WhatsApp to an AI agent. QR scan, voice transcription, access control, media support.
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Preguntas
¿Cómo instalo Claude Whatsapp?
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
¿Claude Whatsapp necesita una clave de API?
Este registro no indica ninguna variable de entorno obligatoria.
¿Qué transporte usa Claude Whatsapp?
Claude Whatsapp se ejecuta localmente por stdio.
¿Cuándo se comprobó Claude Whatsapp por última vez?
Última comprobación: 2026-11-16. WhatsApp channel plugin for Claude Code — connect your WhatsApp to an AI agent. QR scan, voice transcription, access control, media support.