claude-whatsapp-channel
WhatsApp channel for Claude Code — message Claude from your phone, get replies back, approve tool use remotely.
Built on Baileys (WhatsApp Web multi-device API). Mirrors the architecture of the official Telegram and Discord channels.
More screenshots
Chat with Claude via WhatsApp
QR code setup
Disclaimer
This plugin uses an unofficial WhatsApp client (Baileys). This may violate Meta's Terms of Service. Account bans are possible. Use only with your own personal account, at low volume, and at your own risk.
For production business use, see the official WhatsApp Business Cloud API.
Features
- QR code linking — scan once, session persists across restarts
- Pairing code — headless linking without scanning (
/whatsapp:configure pair <phone>)
- Access control — allowlist with pairing codes, same pattern as the official Telegram channel
- Permission relay — approve or deny Claude's tool use from WhatsApp via emoji reactions
- Group support — mention-triggered delivery in group chats
- Voice transcription — automatic speech-to-text for voice messages (Groq/OpenAI Whisper)
- Media handling — images auto-downloaded, other attachments on demand
- Document replies — long responses auto-sent as file attachments
- Full tool set —
reply, react, edit_message, download_attachment
- Auto-reconnect — exponential backoff on disconnects
Prerequisites
- Node.js v22+
- Claude Code v2.1.80+
- A personal WhatsApp account
Installation
Plugin system (recommended)
Inside a Claude Code session:
/plugin marketplace add mgiovani/claude-whatsapp-channel
/plugin install whatsapp@mgiovani-claude-whatsapp-channel
Then start Claude with the channel active:
claude --dangerously-load-development-channels plugin:whatsapp@whatsapp-channel
Why the flag? Channels are in research preview on an Anthropic-curated allowlist. Community plugins aren't on it, so this flag is required.
Manual (settings.json)
git clone https://github.com/mgiovani/claude-whatsapp-channel
cd claude-whatsapp-channel
npm install
Add to ~/.claude/settings.json:
{
"mcpServers": {
"whatsapp": {
"command": "node",
"args": ["--experimental-strip-types", "/absolute/path/to/claude-whatsapp-channel/server.ts"]
}
}
}
Development
git clone https://github.com/mgiovani/claude-whatsapp-channel
cd claude-whatsapp-channel
make dev
This runs claude --plugin-dir . --dangerously-load-development-channels server:whatsapp, loading the plugin from your local checkout with skills and channel active.
Setup (one-time)
Step 1 — Link your WhatsApp account
In Claude, run:
/whatsapp:configure
A QR code appears in the terminal output and the QR image opens in your system viewer. You can also:
- Press Ctrl+O (Cmd+O on Mac) to expand the QR in the terminal
- Run
cat /tmp/whatsapp-qr.txt in another terminal to see the full QR
Scan the QR with WhatsApp:
- iOS: Settings > Linked Devices > Link a Device
- Android: More options > Linked Devices > Link a Device
The QR expires in ~60s. Run /whatsapp:configure qr for a fresh one if needed.
Alternatively, use a pairing code (no scanning needed):
/whatsapp:configure pair +5511999999999
The session persists across restarts.
Step 2 — Approve your number
Send any message from your phone. The channel replies with a 6-character code:
Pairing required — run in Claude Code:
/whatsapp:access pair a3f9b2
Run that in Claude Code. You'll receive "Paired! Say hi to Claude." on WhatsApp.
Step 3 — Lock it down (recommended)
Once your trusted numbers are approved, switch to allowlist mode so no new numbers can trigger pairing:
/whatsapp:access policy allowlist
Usage
Send a WhatsApp message from an approved number. Claude receives it as:
<channel source="whatsapp" chat_id="5511999999999@s.whatsapp.net"
message_id="3EB0..." user="John" ts="2026-03-23T11:00:00Z">
Hey Claude, what's the status of the deploy?
</channel>
Claude uses the reply tool to respond. Messages go directly to WhatsApp.
Permission relay
