WhatsApp-Me

A Claude Code plugin that lets Claude message you on WhatsApp. Get notified on your phone when Claude finishes tasks, runs into errors, or needs your input.

Features

📱 Two-way messaging - Claude can send messages AND wait for your replies
✅ Task completion alerts - Know when work is done
❌ Error notifications - Get alerted when something goes wrong
🤔 Questions via WhatsApp - Answer Claude's questions from your phone

How It Works

Claude Code                    WhatsApp-Me MCP Server (local)
    │                                    │
    │  "I finished the task..."          │
    ▼                                    ▼
Plugin ────stdio──────────────────► MCP Server
                                         │
                                         ├─► ngrok tunnel
                                         │
                                         ▼
                                   WhatsApp Cloud API (Meta)
                                         │
                                         ▼
                                   📱 Your Phone buzzes
                                   You reply via WhatsApp
                                   Text returns to Claude

Quick Start

Step 1: Create Required Accounts

You need two free accounts:

Account	Sign up
Meta Developer	developers.facebook.com
ngrok	ngrok.com

Step 2: Set Up WhatsApp API

📋 Click to expand WhatsApp setup

2.1 Create Meta App

Go to Meta Developer Console
Click Create App → Select Other (This is important to see the Business option)
Select Business as the app type → Click Next
Name your app (e.g., "Message-Me") → Click Create App

2.2 Add WhatsApp Product

In your app dashboard, scroll down to WhatsApp → Click Set up
You will be redirected to the API Setup page in the sidebar

2.3 Get Your Credentials

From the API Setup page:

Note your Phone Number ID (under "From" field)
Important: The token on this page is Temporary (expires in 24 hours). For a permanent setup, follow the steps below.

2.4 Generate Permanent Access Token

To avoid updating your token every 24 hours, create a System User:

Go to Meta Business Settings
Select Users > System Users → Click Add → Name it "Claude-Bot" → Role: Admin
Click Assign Assets → Select Apps → Select your App → Enable Full Control → Save
Select the user again → Click Generate New Token
Select your App → Check whatsapp_business_messaging and whatsapp_business_management
Set Expiration to Never (or the longest available) → Click Generate
Copy this token immediately (it will only be shown once)

2.4 Get App Secret

Go to Settings → Basic
Find App Secret → Click Show → Copy it

2.5 Add Your Phone Number

In API Setup, enter your WhatsApp number in the "To" field
Format: +15551234567 (country code, no spaces)
Click Send Code → Enter the code you receive on WhatsApp

Step 3: Get ngrok Token

📋 Click to expand ngrok setup

Sign up at ngrok.com
Go to Your Authtoken
Copy your authtoken

Step 4: Set Environment Variables

Open ~/.claude/settings.json and add your credentials.

Windows (PowerShell):

notepad "$env:USERPROFILE\.claude\settings.json"

macOS/Linux:

nano ~/.claude/settings.json

Add the following to the env object:

{
  "env": {
    "WHATSAPPME_PHONE_NUMBER_ID": "your_phone_number_id",
    "WHATSAPPME_ACCESS_TOKEN": "your_access_token",
    "WHATSAPPME_APP_SECRET": "your_app_secret",
    "WHATSAPPME_VERIFY_TOKEN": "any_random_string_you_make_up",
    "WHATSAPPME_USER_PHONE_NUMBER": "+15551234567",
    "WHATSAPPME_NGROK_AUTHTOKEN": "your_ngrok_authtoken",
    "WHATSAPPME_PORT": "3333"
  }
}

ℹ️ What each variable does

Variable	Description
`WHATSAPPME_PHONE_NUMBER_ID`	Your Meta WhatsApp sender ID
`WHATSAPPME_ACCESS_TOKEN`	API token to send messages (expires in 24h)
`WHATSAPPME_APP_SECRET`	Used to verify webhook signatures
`WHATSAPPME_VERIFY_TOKEN`	Your custom string to verify webhook setup
`WHATSAPPME_USER_PHONE_NUMBER`	Your phone number to receive messages
`WHATSAPPME_NGROK_AUTHTOKEN`	Authenticates your ngrok tunnel
`WHATSAPPME_PORT`	The local port the server runs on (default: 3333)

Step 5: Install Plugin

In Claude Code terminal, run:

/plugin marketplace add AsharibAli/whatsapp-me
/plugin install whatsappme@whatsappme

Step 6: Get Your Webhook URL & Verify Token

Start Claude Code, and Ask Claude:

What's my webhook URL and verify token?

Copy this webhook url and verify token

Step 7: Configure Webhook

In your Meta App sidebar, go to WhatsApp → Configuration
Under Webhook, click Edit
Enter your details from the get_setup_info tool:
- Callback URL: https://your-ngrok-url/webhook
- Verify Token: Same as your WHATSAPPME_VERIFY_TOKEN
Click Verify and Save
Crucial: Under Webhook fields, find messages → Click Subscribe

Usage

Once configured, Claude will communicate via WhatsApp:

You (terminal): "Create a REST API with authentication"

Claude: [creates files]
📱 WhatsApp: "✅ Created REST API. What would you like next?"
📱 You: "Add tests"

Claude: [adds tests]
📱 WhatsApp: "✅ Added tests. What's next?"
📱 You: "That's all!"

Claude: [stops]

Troubleshooting

Webhook verification fails

Check ngrok is running (look for the URL in terminal)
Verify token must match exactly (case-sensitive)
URL must end with /webhook
Test: curl https://your-ngrok-url/health

Messages not sending

Access token expires after 24 hours - generate a new one
Phone number must be verified in Meta console
Check API quota in Meta dashboard

Messages not receiving

Check "messages" is subscribed in Webhook fields
Verify WHATSAPPME_APP_SECRET matches Meta app secret
Check server logs for signature mismatch errors

ngrok disconnects

Free tier has 2-hour session limit
Restart the plugin to get new tunnel
Consider ngrok paid plan for stable URLs

Development

git clone https://github.com/AsharibAli/whatsapp-me.git
cd whatsapp-me && cd server

bun install
bun run dev

whatsapp-messaging