WhatsApp

Connect a WhatsApp Business number to your Claude Code session via an MCP server.

The MCP server receives WhatsApp messages through Meta's Cloud API webhook, forwards them to your Claude Code session, and provides tools to reply and react. When someone messages your WhatsApp Business number, the server delivers the message to the assistant.

Prerequisites

• Bun — the MCP server runs on Bun. Install with curl -fsSL https://bun.sh/install | bash.
• A Meta Business Account with a Meta App that has the WhatsApp product added.
• A publicly reachable HTTPS endpoint for the webhook (use ngrok for development).

Quick Setup

Default pairing flow for a single-user DM setup. WhatsApp Cloud API is 1:1 only — no group chat support.

1. Create a Meta App with WhatsApp.

1. Go to the Meta App Dashboard and create a new app.
2. Select the "Other" use case, then choose "Business" app type.
3. Once created, find "Connect with customers through WhatsApp" in Use Cases and set it up.
4. Connect your Meta Business Portfolio (create one at business.facebook.com if needed).
5. In the WhatsApp API Setup page, note your Phone Number ID — you'll need it in step 3.

2. Generate a permanent access token.

The API Setup page gives you a temporary 24-hour token for testing. For production:

1. Go to Business Settings > System Users and create a System User (Admin role).
2. Add your Meta App as an asset with full control.
3. Click Generate New Token, select your app, and grant the whatsapp_business_messaging permission.
4. Copy the token — this is your WHATSAPP_ACCESS_TOKEN. It does not expire unless manually revoked.

3. Configure credentials.

These are Claude Code commands — run claude to start a session first.

Using the configure skill:

/whatsapp:configure token EAABwzX... phone 123456789012345 verify my-secret-token

Or create ~/.claude/channels/whatsapp/.env manually:

WHATSAPP_ACCESS_TOKEN=EAABwzX...your-token-here
WHATSAPP_PHONE_NUMBER_ID=123456789012345
WHATSAPP_VERIFY_TOKEN=my-secret-verify-token-123
WHATSAPP_APP_SECRET=abc123...your-app-secret
WHATSAPP_WEBHOOK_PORT=3000

Variable	Required	Description
WHATSAPP_ACCESS_TOKEN	Yes	System User token or temporary test token from Meta
WHATSAPP_PHONE_NUMBER_ID	Yes	Your business phone number ID from the API Setup page
WHATSAPP_VERIFY_TOKEN	Yes	Any secret string — must match what you enter in Meta's webhook config
WHATSAPP_APP_SECRET	Recommended	Found in App Settings > Basic > App Secret. Validates webhook signatures (X-Hub-Signature-256). Without it, signature validation is skipped and a startup warning is logged.
WHATSAPP_WEBHOOK_PORT	No	HTTP port for the webhook server. Default: 3000

4. Set up the webhook.

The server needs to receive HTTPS webhook callbacks from Meta. For development, use ngrok:

ngrok http 3000

Then register the webhook in the Meta App Dashboard:

1. Go to WhatsApp > Configuration > Webhook.
2. Set Callback URL to https://<your-ngrok-url>/webhook.
3. Set Verify token to the same string from WHATSAPP_VERIFY_TOKEN.
4. Click Verify and Save.
5. Subscribe to the messages webhook field.

Note: ngrok URLs change on every restart. You'll need to update the webhook URL in Meta each time. For a persistent setup, use a real domain with HTTPS or Cloudflare Tunnel.

5. Launch with the channel flag.

Exit your session and start a new one:

claude --dangerously-load-development-channels server:whatsapp

6. Pair.

With Claude Code running, message your WhatsApp Business number — it replies with a 6-character pairing code. In your Claude Code session:

/whatsapp:access pair <code>

Your next message reaches the assistant.

7. Lock it down.

Pairing is for capturing phone numbers. Once you're in, switch to allowlist so strangers don't get pairing-code replies:

/whatsapp:access policy allowlist

Access Control

The /whatsapp:access skill manages who can reach you:

Command	Effect
/whatsapp:access	Show current policy, allowlist, and pending pairings
/whatsapp:access pair <code>	Approve a pairing code
/whatsapp:access deny <code>	Discard a pending code
/whatsapp:access allow 15559876543	Add a phone number directly
/whatsapp:access remove 15559876543	Remove from the allowlist
/whatsapp:access policy allowlist	Set DM policy: pairing, allowlist, or disabled
/whatsapp:access set ackReaction 👍	React to incoming messages with an emoji
/whatsapp:access set replyToMode off	Control quote-reply behavior: off, first, or all
/whatsapp:access set textChunkLimit 2000	Max chars per outbound message before splitting
/whatsapp:access set chunkMode newline	Split on paragraph boundaries instead of hard char count

Quick reference: sender IDs are phone numbers without the + prefix (e.g. 15559876543). Default policy is pairing. All state lives in ~/.claude/channels/whatsapp/access.json.

The /whatsapp:configure skill manages credentials, shows setup status, and guides you through the lockdown flow.

Tools Exposed to the Assistant

Tool	Purpose
reply	Send to a chat. Takes chat_id (phone number) + text, optionally reply_to (message ID) for quoting and files (absolute paths) for attachments. Images (.jpg/.png/.gif/.webp) send as photos; other types send as documents. Files are uploaded to WhatsApp's media API first, then sent by media ID. Max 50MB each. Auto-chunks long text. Returns the sent message ID(s).
react	Add an emoji reaction to a message by ID. Any single emoji works — no whitelist restriction (unlike Telegram). Send empty string to remove a reaction.

There is no edit_message tool — WhatsApp Cloud API does not support editing sent messages. If the assistant needs to correct something, it sends a new message.

Media

Inbound: Photos, documents, audio, and video are downloaded to ~/.claude/channels/whatsapp/inbox/ on arrival. The local path is included in the <channel> notification as image_path so the assistant can Read it. WhatsApp compresses photos.

Outbound: The reply tool accepts file paths via the files parameter. Files are uploaded to the WhatsApp media API and sent as image or document messages.

No History or Search

WhatsApp's Cloud API exposes neither message history nor search. The bot only sees messages as they arrive. If the assistant needs earlier context, it will ask you to paste or summarize.

Architecture

This channel differs from Telegram in one key way: webhooks instead of long polling. Telegram's grammy library polls for new messages; WhatsApp's Cloud API pushes messages to your HTTPS endpoint via Meta's webhook system.

The server runs a local HTTP server (Bun.serve()) that handles:

• GET /webhook — Meta's verification handshake
• POST /webhook — incoming messages, validated with X-Hub-Signature-256 when APP_SECRET is configured
• GET /health — health check endpoint

No external dependencies beyond @modelcontextprotocol/sdk — all WhatsApp API calls use native fetch.

Limitations

• No message editing — WhatsApp Cloud API does not support editing sent messages.
• No group chats — WhatsApp Cloud API bots operate 1:1 only.
• Webhook requires HTTPS — Meta only delivers webhooks to HTTPS endpoints. Use ngrok or a reverse proxy for development.
• No message history — the bot only sees messages as they arrive.
• Temporary test tokens expire in 24 hours — use a System User token for production.
• ngrok URL changes on restart — requires re-registering the webhook in Meta each time.

License

Apache-2.0