Eng-Muhammad-Affan WhatsApp Monitoring Skill
Monitor WhatsApp Web for messages using Playwright-based watcher.
Setup
Install Dependencies
uv sync
uv run playwright install chromium
Configure Environment
# WhatsApp session storage
export WHATSAPP_SESSION_PATH=~/.digital_fte/sessions/whatsapp
# Vault path
export VAULT_PATH=./vault
# Check interval (seconds)
export CHECK_INTERVAL=30
# Keywords to monitor
export WHATSAPP_KEYWORDS=urgent,asap,invoice,payment,help,important
# Dry run mode
export DRY_RUN=true
Usage
Start WhatsApp Watcher
# Start monitoring
uv run python scripts/whatsapp_watcher.py --vault ./vault
# With custom keywords
uv run python scripts/whatsapp_watcher.py --keywords "urgent,payment,client"
# With custom interval
uv run python scripts/whatsapp_watcher.py --interval 60
First Run - QR Code Login
- Start the watcher
- WhatsApp Web will load in browser
- Scan QR code with your phone
- Session is saved for future runs
How It Works
- Browser Launch: Opens Chromium with persistent session
- WhatsApp Web: Navigates to web.whatsapp.com
- Message Scanning: Checks unread chats for keywords
- Action File Creation: Creates
.mdfile in/Needs_Action/ - Processing: Claude Code processes action files
Action File Format
When a message matches keywords:
---
type: whatsapp_message
chat_name: John Doe
received: 2026-01-07T10:30:00Z
priority: high
status: pending
matched_keywords: ["urgent", "invoice"]
message_id: John_Doe_20260107_1030
---
# WhatsApp Message
## From
**John Doe**
## Received
2026-01-07 10:30:00
## Priority
HIGH
## Matched Keywords
urgent, invoice
---
## Message Content
Hey, can you send me the invoice urgently?
---
## Suggested Actions
- [ ] Read and understand the message
- [ ] Draft reply (requires approval before sending)
- [ ] Take necessary action based on request
- [ ] Mark as processed
Keyword Detection
Default keywords:
urgent- High priorityasap- High priorityinvoice- Business relatedpayment- Financialhelp- Support requestimportant- High priority
Customize via WHATSAPP_KEYWORDS environment variable.
Integration with Orchestrator
# Start all watchers including WhatsApp
uv run python scripts/orchestrator.py start --watchers filesystem whatsapp
# Process detected messages
uv run python scripts/orchestrator.py process
# Ralph loop for autonomous processing
uv run python scripts/orchestrator.py ralph-loop "Process all WhatsApp messages"
Reply Workflow
- WhatsApp message detected → Action file in
/Needs_Action/ - Claude Code processes → Draft reply created
- Approval file in
/Pending_Approval/ - Human approves → Moves to
/Approved/ - Reply sent via WhatsApp MCP (future) or manual
Environment Variables
# Session storage
WHATSAPP_SESSION_PATH=~/.digital_fte/sessions/whatsapp
# Monitoring
CHECK_INTERVAL=30 # Seconds between checks
WHATSAPP_KEYWORDS=urgent,asap,invoice,payment,help
# Browser
PLAYWRIGHT_HEADLESS=true
# Vault
VAULT_PATH=./vault
# Dry run
DRY_RUN=true
Troubleshooting
| Issue | Solution |
|---|---|
| QR code not showing | Clear session folder and restart |
| No messages detected | Check if WhatsApp Web is loaded |
| Browser crashes | Set PLAYWRIGHT_HEADLESS=false to debug |
| Session expired | Re-scan QR code |
Security Notes
- Session data stored locally in
~/.digital_fte/sessions/whatsapp - Never commit session files to version control
- Use dedicated business WhatsApp account for automation
- Be aware of WhatsApp's terms of service
Related Skills
- email-sending - Email communication
- linkedin-posting - Social media posting