whatsapp-claude-plugin

Drive your Claude Code session from WhatsApp. Choose a **linked device** for a
personal account or the **official WhatsApp Cloud API** for business DMs.
The default Baileys provider connects like WhatsApp Web: pair your phone, then
Claude replies from your own number. Existing installations keep this provider.
The optional Cloud API provider uses Meta's business API and a public HTTPS
webhook, with its own credentials, messaging policies and applicable fees.
Both providers feed the same MCP channel and access gate.
> **Community project.** This plugin is not made or endorsed by Anthropic or Meta.
> Its Baileys provider uses an unofficial linked-device protocol, which may
> conflict with WhatsApp's terms and put the number at risk. The optional Cloud
> provider uses official API transport; confirm your use is permitted under
> Meta's business and AI-provider rules before enabling it.
Installation
The --dangerously-load-development-channels flag matters: it registers the plugin as a **channel**, so an inbound WhatsApp message wakes your session immediately. Without it the tools still load, but nothing wakes the session when messages arrive — they sit unanswered until you (or a watchdog) prompt Claude to check. --channels does not accept this plugin yet (it is not on the research-preview allowlist), so the development flag is currently the only way.
> **Know what this flag does.** Claude Code warns against loading downloaded channels this way: a loaded channel can put text from other people straight into your session. Read this plugin's code before you use it, keep the allowlist to people you trust, and keep permission prompts on. Never combine it with --dangerously-skip-permissions: with prompts off, anyone in an allowlisted chat could get Claude to run commands on your computer.
Inside the session, choose your connection:
The wizard runs in your own terminal so Cloud credentials never pass through
chat. Or run bun scripts/provider.ts choose from the plugin directory.
| Connection | Setup | Main limits |
| ---------------------------------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| Linked device (baileys, default) | Pair your phone; no Meta API credentials | Unofficial protocol; existing personal/group behavior |
| Official (cloud-api) | Meta business number, token, app secret, verify token, public HTTPS webhook | DMs only in this implementation; service window/templates and Meta fees/policies apply |
For linked-device pairing, save your number with
/whatsapp-channel:configure (country code + number, no +). Enter the
printed pairing code in WhatsApp → Settings → Linked Devices → Link a Device →
**Link with phone number instead**, or scan the QR.
For official business DMs, follow Cloud API setup. This
provider does not yet support groups, message editing, phone history/address-book
import or coexistence synchronization. Add an explicitly allowed personal owner;
the business number is never auto-added, and the owner must be set explicitly with
/whatsapp-channel:access set owner . A non-empty key saved in
~/.whatsapp-channel/.env by the terminal tools wins over plugin /config values
for that key; remove it from .env to return it to plugin management.
Configuration readiness is not proof
that the public webhook works. Rates vary; consult
Meta pricing and
FAQ.
Other MCP clients (Codex CLI, Gemini CLI, Cursor)
The server is a plain stdio MCP server, so any MCP client can run it. Two things are Claude Code specific and worth knowing before you start:
- **Inbound messages are not pushed.** Waking a session on an incoming message uses notifications/claude/channel, a Claude Code extension. MCP has no standard equivalent that reaches the model, and other clients drop unknown notifications silently. Elsewhere the plugin is poll-based: call wait_for_messages (parks up to 40s; the first call on a connection returns whatever is already unreplied, later calls only what arrived since) or catch_up / unreplied. Most tool results also carry a count of unreplied messages, so a client finds out there is traffic on its next call. Three do not: unreplied and wait_for_messages, which just returned those very messages, and catch_up with no arguments, which is that count already.