wavi

Read full chat histories. Capture audio. Transcribe voice messages. Without touching the DOM.

Philosophy

WhatsApp Web is a black box. Its DOM changes with every deploy, its CSS selectors rotate without warning, and its JavaScript API is private. Any scraper that reads the DOM is brittle by design.

wavi takes a different bet: what a human sees on screen is stable even when the internals change. Chat bubbles look like chat bubbles. Timestamps look like timestamps. Voice messages look like voice messages. That rendering contract is anchored to human expectation — it barely changes across WA versions.

Why this matters beyond WhatsApp

Every technique in this codebase — bubble detection, OCR timestamp extraction, blob URL interception, DOM anchor deduplication — is a reusable building block. The same approach applies to Telegram Web, Slack, or any chat UI that follows a similar visual grammar.

We are building a vocabulary for visual automation. Each solved problem here is a solved problem everywhere.

Speed is not the enemy

Chrome headless + Playwright CDP + Apple Vision OCR is fast enough. A 300-message chat captures in under 2 minutes. A 1000-message chat in under 10. That's fast enough for any real workflow.

The system prioritizes correctness over raw speed: DOM anchor deduplication ensures no message appears twice even across overlapping scroll windows; DOM IDs take priority over OCR text for dedup keys because OCR is imperfect. Every piece has a fallback.

Quick start

# Isolated global install via pipx
pipx install --editable .

# Or dev install in the project venv
pip install -e ".[dev]"

wavi connect --open  # first-time: opens QR page in browser
wavi connect         # subsequent: restores session headlessly
wavi status          # verify: daemon=running, session=restored

echo "GROQ_API_KEY=gsk_..." >> .env

wavi get default "Ana García"
# → output/ana_garcía/history_bubbles.json
# → output/ana_garcía/iter_*/screenshot.png
# → output/ana_garcía/iter_*/audio_*.ogg

wavi send default "Ana García" "Hola!"
wavi send default "+54 9 11 5561 2767" "test" --screenshot-out sent.png

wavi list-contacts
# → output/contacts/contacts_list.json
# → output/contacts/screenshot.png

Commands

All commands accept an optional SESSION argument (default: "default"). Multiple sessions can run simultaneously on different CDP ports.

List Contacts — output

Running wavi list-contacts opens the WhatsApp "New chat" panel, scrolls the full virtualized list extracting contacts via DOM ([role="listitem"]), and writes two files to output/<session>/contacts/ — overwriting on every run:

• contacts_list.json — array of {name, subtitle} objects
• screenshot.png — full 1280×1920 browser viewport to confirm the panel state

Browser viewport — 1280 px wide (ADR-002)

The screenshot below is the actual Chrome viewport captured during the last run. The "New chat" panel occupies the left ~580 px (same as the sidebar used by the message capture pipeline). The right panel shows the previously open chat — irrelevant to contact extraction.

Contact list panel (left 580 px)

Full viewport (1280 px)

Output structure

output/contacts/          # overwritten on every run
  contacts_list.json      # [{"name": "...", "subtitle": "..."}, ...]
  screenshot.png          # 1280×1920 browser viewport

Check Updates — output

Running wavi check-updates inspects the WhatsApp sidebar for new inbound messages. Detection is DOM-state based: every visible chat row is captured as {name, last_message, timestamp, direction} and compared against the previous run's saved state in updates.json.

Algorithm

1. ensure_chat_list() — close the New Chat panel if open, press Escape ×3 to clear search/overlays, wait for the chat list.
2. extract_sidebar_updates() — snapshot every visible chat row via DOM. direction is outbound when a delivery-tick icon (msg-check, msg-dbl-check, …) is present in the preview row, inbound otherwise.
3. No previous state (or --reset) → status=first_run, save baseline and return.
4. Compare row-by-row against the previous state: any inbound row whose last_message or timestamp changed → status=updates with those rows in new_inbound. No changes → status=no_updates.
5. Write updates.json (new state, replaces the old baseline) and snapshot_current.png.

Limitation: only the last visible message per chat is tracked. If several messages arrive between two checks, only the most recent one is reported per contact — use wavi get afterwards to retrieve the full history.

Output structure

output/<session>/last-updates/
  snapshot_current.png  # sidebar at this run (debugging)
  updates.json          # {status, checked_at, contacts: [{name, last_message, timestamp, direction}], new_inbound}

Status values

Sequence diagram

Architecture

System overview

wavi is a thin CLI on top of a three-layer stack: session management (Chrome CDP via Playwright), vision (pure image processing), and orchestration (WARunner ties them together with scroll logic and audio capture).

Module dependency graph

Command sequences

One sequence diagram per command. Variants show only the delta from the base flow. Solid arrows (→→) = action/request; dashed arrows (- -→→) = response/return.

wavi get — full history capture

wavi get --newest — incremental update

Loads the existing history_bubbles.json and stops scrolling as soon as the first already-known message is found. New messages are prepended and IDs renumbered.

wavi get --from YYYY-MM-DD — date-bounded capture

Stops scrolling when the oldest visible day-separator pill is earlier than the requested date. Bubbles older than from_date are dropped from that iteration.

wavi get --grow — paged history capture

Loads history_bubbles.json and grow_checkpoint.json, fast-forwards past known messages, then captures --max-iter N new-content iterations toward the past. Each run extends the history by one block. When scrollTop reaches 0 the checkpoint is marked complete and future runs exit immediately. Incompatible with --newest.

wavi send

wavi connect — session already active (fast path)

wavi connect — QR scan required

Optimistic headless probe first. If QR is needed, captures it headlessly and writes a local HTML file — no visible Chrome window ever opens. Session dir is renamed to the phone number once scanned. QR expiry detected via data-ref change.

wavi stop

wavi status

wavi queue

wavi bubbles — offline vision pipeline

No browser. Runs entirely from a saved PNG file. Useful for debugging detection and OCR on a specific frame.

wavi list-contacts

DOM-based extraction — no vision pipeline. Opens the "New chat" panel, reads [role="listitem"] elements while scrolling the virtualized list to the bottom (anchor-based overlap dedup), writes contacts_list.json + screenshot.png to output/<session>/contacts/ (overwritten on every run).

Key classes

Browser interaction layer

WASession interacts with WhatsApp Web using physical coordinates and keyboard events, not DOM selectors or page.locator() calls. This is a deliberate choice: WA's DOM is obfuscated and changes with every deploy, but the visual layout is stable. If a button gets a new data-testid, wavi doesn't care — it clicks wherever the button appears on screen.

Coordinate translation — vision pipeline works in crop-panel pixels (sidebar and header stripped). WASession maps them back to viewport pixels before any click:

viewport_x = crop_x + SIDEBAR_X  (580 px)
viewport_y = crop_y + HEADER_Y   ( 60 px)

→ page.mouse.click(viewport_x, viewport_y)   ← always a coordinate click

DOM queries are used only when there is no alternative: to obtain the coordinates of a dynamic element (compose box), to read scroll state, to read DOM data-id attributes for deduplication, and to capture blob URLs via JS injection.

navigate_to_contact — how it works

send_message — how it works

Vision pipeline

The vision pipeline is pure — no browser, no network, no side effects. It takes a PNG file and returns a list of classified Bubbles. This makes it fully testable without mocking anything real.

Vision pipeline — flowchart

Test suite

All tests run offline — no browser, no real WA account, no API calls. Browser methods are mocked with AsyncMock. The vision tests use synthetic images generated in-memory with Pillow + numpy.

Design decisions

Key architectural choices and the reasoning behind them.