WhatsApp Web has long been a tempting target for automation enthusiasts, yet its everโ€‘changing frontend and aggressive antiโ€‘scraping measures make traditional DOMโ€‘based approaches fragile. The newly released waviโ€‘lib on PyPI sidesteps these hurdles by adopting a visionโ€‘first pipeline: it captures a screenshot of the WhatsApp Web interface, runs OCR to recognise text bubbles, and then translates visual coordinates into clicks. This method sidesteps the obfuscated DOM that WhatsApp employs to deter bots, providing a more resilient way to read and send messages. Because the tool works purely on what the user sees, it remains functional even when class names or data attributes shift after a WhatsApp update.

At its core, waviโ€‘lib is a commandโ€‘line interface that accepts an alias instead of a raw phone number, looking up the corresponding session data stored in data/sessions/aliases.json. This abstraction lets users refer to contacts by memorable names, simplifying scripts and reducing the chance of dialing errors. The CLI is built around a small set of focused commandsโ€”wavi connect, wavi send, wavi get, wavi edit, and wavi replyโ€”each of which orchestrates the vision pipeline, interacts with the browser via Playwright, and returns structured results. By keeping the surface area minimal, the project lowers the barrier for developers who want to embed WhatsApp capabilities into larger automation workflows without wrestling with lowโ€‘level browser intricacies.

The decision to rely on vision rather than direct DOM scraping stems from WhatsApp Webโ€™s deliberate efforts to hide message content behind randomised attributes and shadow DOM structures. When a bot attempts to query elements by selector, it often receives empty nodes or stale references, leading to flaky scripts that break after minor UI tweaks. By contrast, the screenshotโ€ฏโ†’โ€ฏOCRโ€ฏโ†’โ€ฏbubble detection flow treats the chat window as an image, extracting text based on visual patterns that are far less prone to obfuscation. This approach also naturally handles emojis, styled text, and multiโ€‘line bubbles, which would otherwise require complex DOM traversal logic.

Three core modules drive the vision pipeline: element_detector.py locates UI components such as the chat list, message bubbles, and input box; vision.py handles image preprocessing, OCR execution (via Tesseract or similar), and coordinate mapping; runner.py ties everything together, invoking the appropriate sequences for each CLI command. This separation of concerns makes the codebase approachable for contributors who may want to improve OCR accuracy, add language support, or plug in alternative computerโ€‘vision backends. The projectโ€™s MIT licence further encourages community extensions, ensuring that enhancements can be shared freely.

While the vision pipeline handles message content, navigation and sidebar state still benefit from lightweight DOM inspection. In session.py, a series of JavaScript constants store selectors for critical UI elementsโ€”such as the newโ€‘chat button, archive icon, and pinnedโ€‘chat indicatorโ€”each accompanied by a comment that notes the original selector and a visionโ€‘based fallback. Should a WhatsApp update break a selector, developers can consult the โ€œDOM scraping inventoryโ€ block at the top of the file to implement a visual alternative without rewriting large swaths of code. This hybrid strategy gives the best of both worlds: fast, reliable state checks where the DOM is stable, and a safety net where it is not.

To preserve a healthy WhatsApp Web session, waviโ€‘lib launches Chrome as a longโ€‘lived background process via wavi connect. Playwright then attaches to this existing tab for each operation, connecting and disconnecting without ever terminating the browser process. Killing Chrome midโ€‘session would interrupt IndexedDB write transactions, corrupting the underlying LevelDB store and forcing a full QRโ€‘code reโ€‘scan on the next launch. By keeping the browser alive, the tool avoids these costly disruptions and maintains persistent authentication tokens, which is essential for unattended automation that must run for hours or days.

Two operations are explicitly prohibited when interacting with the WhatsApp tab through raw Chrome DevTools Protocol: calling Page.reload or invoking Storage.clearDataForOrigin. Both actions can abort inโ€‘flight IndexedDB transactions, leading to database corruption. A reload merely forces WhatsApp to rebuild its state from scratch, while clearing origin data deletes auth tokens entirely, compelling the user to scan a QR code again. The documentation stresses that any recovery from an unresponsive state must go through the sanctioned wavi reload command, which safely navigates to about:blank before allowing WhatsApp to flush its pending writes.

When WhatsApp Web becomes sluggish or hits internal throttling thresholds, the recommended safe cycle is to pause automation, let the browser recover, and then resume via the wavi CLI or the accompanying HTTP API (wavi serve). If wavi reload signals a qr_needed state, the system should alert a human operator rather than attempting a programmatic recovery, as automated attempts to reโ€‘authenticate risk tripping antiโ€‘abuse mechanisms. This conservative approach protects both the integrity of the WhatsApp session and the reputation of the automating entity, reducing the likelihood of temporary bans or captchas.

Session state, including checkpoints for incremental message retrieval, is persisted under <wavi output dir>/<session>/<contact>/grow_checkpoint.json. Deleting this file (alongside the companion history_bubbles.json) forces a fresh start, causing waviโ€‘lib to reโ€‘scan the entire chat history from the most recent message backward. This design offers a clean way to reset state after a major WhatsApp UI change or after experimenting with new vision parameters, ensuring that developers can iterate without carrying forward stale caches.

Editing an existing message showcases the precision of the vision workflow: waviโ€‘lib searches the chat bubble OCR output for the userโ€™s own message that contains a supplied fragment (caseโ€‘ and accentโ€‘insensitive). If exactly one match is found and the message is younger than fifteen minutes, the tool opens WhatsAppโ€™s edit dialog, prefills it with the original text, applies the fragment transformation, verifies the editorโ€™s content matches the intended result, and then saves the edit. Any ambiguityโ€”zero matches, multiple matches, or an outdated messageโ€”triggers a safe failure where nothing is altered, and the CLI prints helpful diagnostics to guide the user toward a more specific fragment.

Replying with quotation follows a similarly rigorous visual route. Starting from the latest visible bubbles, waviโ€‘lib performs OCR across up to four screens of chat history, seeking a bubble (incoming or outgoing) whose inner text matches the query, ignoring any text that appears inside a quoted block. Once a unique target is identified, the tool rightโ€‘clicks the bubble, selects the โ€œResponderโ€ option from the OCRโ€‘detected context menu, confirms that the quote pane displays the correct message, and then sends the supplied reply text. Should the OCR step return several candidates, the user can disambiguate by specifying a sender with --from or picking an index via --index N. Any error at any stage triggers an escape sequence that closes the quote panel, leaving the chat in a clean state.

Media handling demonstrates the libraryโ€™s attention to completeness: waviโ€‘lib opens the newest photo or video in the chatโ€™s media viewer, then walks the collection backward using the leftโ€‘arrow key, downloading each file at full resolution. Images are sourced directly from the viewerโ€™s blob URL, while videos are fetched in byteโ€‘range chunks from WhatsAppโ€™s /stream/video endpoint, guaranteeing that the downloaded files match the originals rather than the lowโ€‘resolution thumbnails shown in bubbles. Each artefact is stored under <wavi output dir>/<session>/<contact>/media/ with a timestampโ€‘based filename and an accompanying media.json record that captures sender, timestamp, byte size, and SHAโ€‘1 hash, enabling idempotent reโ€‘runs that skip alreadyโ€‘acquired items.

Finally, the wavi watch command compares a snapshot of the sidebarโ€”last message text and timestamp per chatโ€”against the previous saved state to surface updates. Directionality is inferred from the presence of tick icons (singleโ€‘check for sent, doubleโ€‘check for delivered) to distinguish outbound from inbound messages. A known limitation is that only the most recent visible bubble per chat is recorded; if several messages arrive between checks, only the latest is reported. For exhaustive history retrieval after an update trigger, users should run wavi get <contact> to pull the full log. Armed with these insights, developers can confidently integrate waviโ€‘lib into notification bots, customerโ€‘service pipelines, or personal productivity tools, while adhering to the safeโ€‘shutdown practices that keep WhatsApp sessions healthy and QRโ€‘code scans rare.