whatsapp

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="[email protected]"
         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