WhatsApp + Claude integration: auto-reply to messages via Anthropic API

[brando90]

Summary

Add the ability to receive WhatsApp messages and auto-reply using Claude (Anthropic API). The goal is to respond to any WhatsApp messages through Claude Code without manual effort.

What's Been Built (Phase 1 — this branch)

Branch: claude/whatsapp-integration-iRBAL

py_src/uutils/whatsapp_uu.py — expanded with:

• WhatsAppClaudeBot class — manages per-contact conversation history in memory, calls Claude API to generate context-aware replies, sends them back via WhatsApp
• create_whatsapp_webhook_app() — creates a Flask app that serves as a Meta webhook endpoint (GET for verification, POST for incoming messages)
• run_whatsapp_bot() — one-liner to start the full bot server
• mark_as_read() — marks incoming messages as read via Meta API
• _extract_messages() — parses Meta webhook payloads to extract text messages
• _verify_webhook_signature() — HMAC-SHA256 verification of Meta webhook payloads
• Conversation history trimming (max 50 messages per contact)

playground/whatsapp_claude/test_whatsapp_claude_bot.py — test script with:

• Dry-run tests (no API keys needed): send, phone normalization, message extraction, conversation management, webhook verification, webhook message handling
• Claude integration tests (--claude flag): actual Claude reply generation with conversation context
• Full webhook + Claude tests (--full flag): simulated Meta webhook payloads with Claude auto-replies
• Server mode (--serve flag): starts the actual bot

pyproject.toml — added flask as optional dependency:

pip install -e "~/ultimate-utils[whatsapp]"

How to Use

Quick test (no keys needed):

python playground/whatsapp_claude/test_whatsapp_claude_bot.py

Programmatic (Claude replies without server):

from uutils.whatsapp_uu import WhatsAppClaudeBot
bot = WhatsAppClaudeBot()
reply = bot.generate_reply("+14155551234", "Hey, what's up?")

Full bot server:

from uutils.whatsapp_uu import run_whatsapp_bot
run_whatsapp_bot()  # starts Flask on port 5000

Setup Required (Meta / WhatsApp Business)

1. Meta Business Account — https://business.facebook.com/
2. Meta App — https://developers.facebook.com/apps/ → create app → add WhatsApp product
3. Access Token + Phone Number ID — from WhatsApp > API Setup in the developer console
4. Save config:

   cat > ~/keys/whatsapp_api_config.json << 'JSON'
   {
       "provider": "meta",
       "access_token": "YOUR_ACCESS_TOKEN",
       "phone_number_id": "YOUR_PHONE_NUMBER_ID",
       "api_version": "v21.0",
       "verify_token": "YOUR_WEBHOOK_VERIFY_TOKEN"
   }
   JSON
   chmod 600 ~/keys/whatsapp_api_config.json

5. Anthropic API key: export ANTHROPIC_API_KEY="sk-ant-..." or save to ~/keys/anthropic_api_key.txt
6. Expose webhook: ngrok http 5000 for local dev, or deploy behind HTTPS
7. Configure webhook in Meta console: URL = https://YOUR_DOMAIN/webhook, subscribe to messages

Future Work (Phases 2-3)

• Persistent conversation history (JSON files in ~/data/whatsapp_conversations/)
• Phone number allowlist (restrict who can trigger Claude)
• Per-phone rate limiting (prevent abuse / runaway loops)
• Background thread processing (Meta requires webhook response within 5 seconds)
• Image message support (download media, use Claude vision)
• Voice message handling
• Customizable system prompts per contact
• Template message support for initiating conversations outside 24-hour window