WhatsApp + Claude auto-reply integration

[brando90]

Summary

• Adds WhatsAppClaudeBot class + Flask webhook server to whatsapp_uu.py so incoming WhatsApp messages get auto-replied by Claude
• Adds dry-run test suite (playground/whatsapp_claude/test_whatsapp_claude_bot.py) — all 6 tests pass with no API keys needed
• Adds flask as optional dependency (pip install -e ".[whatsapp]")

Closes #34

---

Step-by-Step Setup Guide (what you need to do)

Step 1: Create a Meta Business Account (5 min)

1. Go to https://business.facebook.com/
2. Click "Create Account"
3. Use your real name / business name (personal is fine — "Brando Research" or whatever)
4. Confirm your email

Step 2: Create a Meta Developer App (5 min)

1. Go to https://developers.facebook.com/apps/
2. Click "Create App"
3. Choose app type: "Business"
4. Give it a name like "WhatsApp Claude Bot"
5. Select your Business Account from Step 1
6. Click "Create App"

Step 3: Add WhatsApp to Your App (2 min)

1. In your new app's dashboard, find "Add Products" in the left sidebar
2. Find "WhatsApp" and click "Set Up"
3. It will walk you through connecting your Business Account

Step 4: Get Your Credentials (5 min)

In the Meta Developer Dashboard, go to WhatsApp → API Setup. You'll see:

1. Phone Number ID — displayed on the page (a numeric string like 123456789012345)
2. Access Token — click "Generate" for a temporary token (lasts 24h), or for a permanent one:
   • Go to Business Settings → System Users → Add → create a system user
   • Give it admin role, then Generate Token with whatsapp_business_messaging permission
3. Test Phone Number — Meta gives you a free test number to send from (shown on API Setup page)
4. App Secret — go to App Settings → Basic → reveal the App Secret

Step 5: Save Your Credentials Locally (2 min)

# Create the config file
cat > ~/keys/whatsapp_api_config.json << 'JSON'
{
    "provider": "meta",
    "access_token": "PASTE_YOUR_ACCESS_TOKEN_HERE",
    "phone_number_id": "PASTE_YOUR_PHONE_NUMBER_ID_HERE",
    "api_version": "v21.0",
    "verify_token": "pick_any_secret_string_you_want_like_uutils_whatsapp_2024"
}
JSON
chmod 600 ~/keys/whatsapp_api_config.json

# Make sure your Anthropic key is set
export ANTHROPIC_API_KEY="sk-ant-your-key-here"
# OR save it to a file:
# echo "sk-ant-your-key-here" > ~/keys/anthropic_api_key.txt && chmod 600 ~/keys/anthropic_api_key.txt

Step 6: Expose Your Local Server to the Internet (2 min)

Meta needs to reach your computer via HTTPS. Easiest way:

# Install ngrok (one time)
# Mac: brew install ngrok
# Linux: snap install ngrok
# Or download from https://ngrok.com/download

# Start the tunnel
ngrok http 5000

ngrok will show something like: https://abc123.ngrok-free.app — copy this URL.

Step 7: Configure the Webhook in Meta (3 min)

1. In Meta Developer Dashboard, go to WhatsApp → Configuration
2. Under Webhook, click "Edit"
3. Callback URL: paste your ngrok URL + /webhook, e.g.: https://abc123.ngrok-free.app/webhook
4. Verify Token: paste the same verify_token you put in your config (e.g., uutils_whatsapp_2024)
5. Click "Verify and Save" — Meta will ping your server (must be running first! See Step 8)
6. Under Webhook Fields, click "Manage" and subscribe to messages

Step 8: Start the Bot! (1 min)

# Start the WhatsApp Claude bot
python playground/whatsapp_claude/test_whatsapp_claude_bot.py --serve

# Or from Python:
# from uutils.whatsapp_uu import run_whatsapp_bot
# run_whatsapp_bot()

Important: Start the bot BEFORE Step 7's "Verify and Save" — Meta needs to reach /webhook to verify.

Step 9: Test It

1. Meta gives you up to 5 test phone numbers in the API Setup page
2. Add your personal phone number as a test recipient
3. Send a message to the WhatsApp Business number from your phone
4. Claude should auto-reply within a few seconds!

---

Quick Reference — What Each Credential Is

Credential	Where to find it	What it does
access_token	WhatsApp → API Setup → Generate Token	Authenticates your API calls to send messages
phone_number_id	WhatsApp → API Setup (shown on page)	Identifies which WhatsApp number to send from
verify_token	You make this up (any string)	Meta sends this back during webhook setup to prove it's you
app_secret	App Settings → Basic (optional)	Verifies webhook payloads are really from Meta
ANTHROPIC_API_KEY	console.anthropic.com	For Claude to generate replies

Test plan

• Dry-run tests pass (no API keys): python playground/whatsapp_claude/test_whatsapp_claude_bot.py
• Claude integration test with API key: python playground/whatsapp_claude/test_whatsapp_claude_bot.py --claude
• Full webhook + send test: python playground/whatsapp_claude/test_whatsapp_claude_bot.py --full
• End-to-end with real WhatsApp Business account

https://claude.ai/code/session_01TYqKRGFxpAo5GY1SnGFLh3