wavi — WhatsApp Web Automation via Vision

CLI tool for WhatsApp Web automation. Extracts message history using a vision pipeline (screenshot → OCR → bubbles), and handles navigation and sidebar state via DOM scraping.

Commands

Session aliases

All commands accept an alias in place of a phone number. Aliases are stored in data/sessions/aliases.json.

wavi alias set pulpo-bot 5491155612767
wavi alias set mateo 5491122608221
wavi status pulpo-bot       # same as: wavi status 5491155612767
wavi get mateo "Contacto"

Architecture

Vision pipeline (wavi get)

Screenshot → Crop chat panel → Color-mask detection → Bbox extraction
    ↓
    OCR (tiled) → Timestamp extraction → Message classification → Bubble list

Used for message content because WhatsApp Web obfuscates the message DOM in ways that make direct scraping unreliable.

Key files: element_detector.py, vision.py, runner.py

DOM scraping

Navigation and sidebar state use JavaScript evaluated directly on the page. Each JS constant in session.py has a comment documenting its key selector and the vision-based fallback to implement if the selector breaks after a WA update. When a DOM-scraped feature stops working, check session.py → "DOM scraping inventory" block at the top.

Chrome daemon

Chrome runs as a long-lived background process (started by wavi connect). Playwright connects and disconnects for each operation without ever killing Chrome. Killing Chrome mid-session corrupts WA's IndexedDB and invalidates the session. Shutdown is done only via wavi stop, which navigates to about:blank first so WA can flush state.

⚠️ Session safety — critical rules

Never call Page.reload or Storage.clearDataForOrigin on the WhatsApp tab via raw CDP.

WhatsApp Web holds in-flight IndexedDB write transactions while running. Interrupting the page mid-transaction (via Page.reload, Page.navigate, or storage wipe) corrupts the LevelDB database and forces a full QR re-scan. Storage.clearDataForOrigin is worse — it deletes auth tokens entirely.

If WA becomes unresponsive or throttled, use the safe cycle:

# Option A — soft reload (~15s, Chrome keeps running)
wavi reload pulpo-bot
# → session=restored  ✓
# → session=qr_needed  auth lost, need QR scan

# Option B — full restart (~30s)
wavi stop pulpo-bot && wavi connect pulpo-bot

External agents (Pulpo, scripts, automation): never send CDP commands directly to the WA tab. Always go through wavi CLI or the HTTP API (wavi serve). If wavi reload returns qr_needed, alert a human — do not attempt to recover programmatically.

Setup

# Install uv if needed
curl -LsSf https://astral.sh/uv/install.sh | sh

git clone <repo> && cd wavi
uv sync

Quick start

# 1. Start daemon and scan QR
wavi connect

# 2. Extract message history
wavi get "Contact Name"

# 2b. Long chat — page through in blocks of 10 iterations
wavi get "Contact Name" --grow --max-iter 10   # block 1
wavi get "Contact Name" --grow --max-iter 10   # block 2 (continues where block 1 stopped)
# repeat until "history is now complete" or no more messages

# 3. Poll for new messages
wavi check-updates           # first run: saves baseline
wavi check-updates           # subsequent: no_updates or updates + contact list

wavi get flags

--grow workflow for long chats

wavi get "Contact" --grow --max-iter 10   # run 1: captures first 10 new-content iterations
wavi get "Contact" --grow --max-iter 10   # run 2: fast-forwards to boundary, captures next 10
# repeat — prints "history is now complete" when scrollTop reaches 0

State is stored in output/<session>/<contact>/grow_checkpoint.json. Delete it to restart from scratch (also delete history_bubbles.json).

check-updates behavior

Compares the sidebar snapshot (last message + timestamp per chat) against the previous saved state. Reports a contact as updated only when:

• its last_message changed, and
• direction == "inbound" (outbound messages and re-reads are ignored)

Direction is inferred from tick icons (msg-check, msg-dbl-check, etc.) — present → outbound; absent → inbound.

Limitation: only the last visible message per chat is tracked. If multiple messages arrive between two checks, only the most recent is reported per contact. Use wavi get <contact> to retrieve the full history after detection.

Development

make ocr                  # compile the OCR helper to bin/ocr_vision (arm64, ~4x faster pipeline)
make hooks                # git hooks: ruff on commit, ruff+pytest on push (bypass: --no-verify)
uv run pytest tests/ -v   # unit tests (offline, mocked browser)
make corpus               # vision eval on golden screenshots (real OCR, see tests/corpus/README.md)

WAVI_TIMING=1 prints a per-stage timing breakdown of each analyze() run. Roadmap and audit: docs/plan-mejoras.md, docs/audit-checklist.md.

Key files:

• session.py — Chrome CDP connection + all DOM scraping JS (see inventory block)
• runner.py — Orchestration: vision pipeline, check_updates, list_contacts
• element_detector.py — Color-mask morphology for bubble detection
• vision.py — OCR, classification, timestamp extraction

Debugging

wavi bubbles /path/to/screenshot.png --debug

Produces screenshot_debug.png with annotated boxes:

• Green: sent messages
• Blue: received messages
• Red crosses: audio play button targets