WhatsApp automation has long been a challenging frontier for developers and power users alike. The platformโ€™s web client deliberately obfuscates its DOM to deter scraping, making traditional approaches brittle and prone to breaking with each UI update. Enter wavi-lib, a newly released PyPI package that sidesteps these obstacles by adopting a vision-first strategy. Instead of relying solely on fragile HTML selectors, the library captures screenshots of the WhatsApp Web interface, runs optical character recognition (OCR) on those images, and then interprets the resulting text bubbles to drive actions. This approach mirrors how a human user perceives the chat, granting the automation a level of resilience that pure DOMโ€‘based scripts simply cannot match. By treating the screen as the source of truth, wavi-lib opens the door to reliable, longโ€‘running automation that can survive the frequent tweaks WhatsApp pushes to its web client.

The core of wavi-libโ€™s vision pipeline consists of three tightly coupled stages: screenshot acquisition, OCR processing, and bubble detection. First, a headless Chrome instance renders the current WhatsApp Web view, and a screenshot is captured at a resolution fine enough to preserve legible text. Next, an OCR engineโ€”typically Tesseract or a comparable neural modelโ€”translates the visual glyphs into machineโ€‘readable strings, preserving layout information that lets the algorithm infer where each message bubble begins and ends. Finally, a custom bubble detector groups adjacent text fragments into logical chat units, associating each with metadata such as sender, timestamp, and message type. This pipeline is encapsulated in the vision.py module, which exposes a clean API for higherโ€‘level operations like reading history, locating specific messages, or detecting media thumbnails. Because the process works on rendered pixels, it remains immune to the classโ€‘name hashโ€‘obfuscation and dynamic attribute changes that plague pure DOM scrapers.

Beyond reading messages, wavi-lib needs a reliable way to address contacts without forcing users to remember raw phone numbers. To that end, the tool introduces an alias system stored in data/sessions/aliases.json. Each alias is a humanโ€‘friendly labelโ€”such as “Mom” or “Support Team”โ€”that maps to a specific WhatsApp identifier (phone number or group JID). When a command is issued, the CLI first consults this JSON file to resolve the alias before proceeding with any vision or DOM interaction. This indirection not only improves usability but also adds a layer of operational safety: administrators can rotate or retire numbers without rewriting scripts, and the JSON format makes it trivial to versionโ€‘control alias lists alongside automation playbooks. The library also includes helper functions to add, remove, and list aliases, ensuring that the mapping stays synchronized with the underlying sessions directory where Chrome profiles and state artifacts reside.

Under the hood, wavi-libโ€™s functionality is split into three primary modules that reflect distinct concerns. element_detector.py houses the lowโ€‘level logic for locating UI elementsโ€”whether via visionโ€‘based contour analysis or DOM selectorsโ€”providing a unified interface that higher layers can call without knowing the underlying technique. vision.py, as described earlier, encapsulates the screenshotโ€‘OCRโ€‘bubble pipeline and offers functions such as get_chat_history, find_message_by_text, and extract_media_thumbnails. runner.py orchestrates the sequence of actions for each CLI command, managing state transitions, error handling, and verification steps. This modular separation makes the codebase approachable for contributors: a developer wanting to improve OCR accuracy can focus on vision.py, while someone aiming to support a new WhatsApp feature (like reactions) can add the appropriate detection logic in element_detector.py and wire it up through runner.py without disturbing the rest of the system.

While vision excels at reading message content, certain aspects of WhatsApp Webโ€”such as opening the sidebar, navigating between chats, or checking connection statusโ€”are still more efficiently handled via the DOM. wavi-lib therefore employs a hybrid approach: it attempts to locate key UI components using JavaScript selectors evaluated directly in the page context, but each selector is annotated with a fallback visionโ€‘based implementation. These annotations live in session.py, where a dedicated โ€œDOM scraping inventoryโ€ block lists every selector alongside a comment describing the exact vision technique to use if the selector breaks after a WhatsApp update. This design transforms what could be a frantic scramble to patch broken selectors into a predictable maintenance routine: when a test fails, developers consult the inventory, implement the suggested vision fallback, and verify that the automation continues to work. The result is a library that gracefully degrades to vision when needed, preserving functionality even as WhatsApp evolves its internal markup.

One of the most subtle yet critical aspects of wavi-lib is its management of the Chrome browser instance that underlies WhatsApp Web. Rather than launching and tearing down Chrome for every individual operationโ€”a pattern that would be excruciatingly slowโ€”the library starts a longโ€‘lived Chrome process via the wavi connect command. This persistent browser hosts a dedicated WhatsApp Web tab that remains logged in and ready. Individual commands, whether issued through the CLI or the optional HTTP API (wavi serve), use Playwright to attach to this existing tab, perform the required actions, and then detach without closing the browser. This approach drastically reduces latency and avoids the costly QRโ€‘code reโ€‘scan cycle that would occur if the session were repeatedly destroyed. However, it also places a premium on proper shutdown: killing Chrome abruptly can corrupt WhatsAppโ€™s IndexedDB store, forcing a full reโ€‘authentication. To prevent this, the wavi stop command first navigates the tab to about:blank, giving IndexedDB a chance to flush pending transactions before the browser is terminated.

The underlying reason for this careful shutdown procedure lies in how WhatsApp Web persists data. While the web client is active, it maintains ongoing IndexedDB write transactions that track message receipts, draft compositions, and sync state. If the page is interrupted midโ€‘transactionโ€”by a sudden Page.reload, a navigation to another URL, or a wholesale storage wipeโ€”the LevelDB backend that underlies IndexedDB can become corrupted. Corruption manifests as an unreadable database, which WhatsApp interprets as a sign of tampering and responds to by wiping the local auth cache and demanding a fresh QR code scan. Even more destructive is calling Storage.clearDataForOrigin on the WhatsApp origin, which not only corrupts the database but also deletes the authentication tokens stored in localStorage, effectively logging the user out and erasing any sessionโ€‘specific settings. wavi-libโ€™s documentation therefore stresses that any automation framework must avoid raw CDP calls that trigger these actions; instead, all stateโ€‘changing operations should funnel through the libraryโ€™s sanctioned methods, which respect the transactional boundaries of the web app.

Even with meticulous lifecycle management, WhatsApp Web can occasionally become unresponsive or be subjected to serverโ€‘side throttling, especially during highโ€‘volume automation runs. In such scenarios, wavi-lib prescribes a safe recovery cycle that minimizes the risk of permanent session damage. First, the automation should cease issuing new commands and allow the existing Chrome process to sit idle for a brief period, giving the web client a chance to recover from temporary load spikes. If responsiveness does not return, the operator should invoke wavi reload, which instructs the library to refresh the page state through Playwright while preserving the underlying Chrome process. Should this reload return a signal indicating qr_neededโ€”meaning the session has been invalidatedโ€”the appropriate response is to alert a human operator rather than attempting any programmatic reโ€‘login. Blindly trying to recover by clearing cookies, injecting scripts, or repeatedly reloading the page often exacerbates the problem, leading to a cycle of authentication failures that can ultimately trigger antiโ€‘abuse mechanisms on WhatsAppโ€™s side. By treating a qr_needed signal as a manualโ€‘intervention event, operators maintain control and avoid unintentional violations of the platformโ€™s terms of service.

State persistence is another area where wavi-lib demonstrates thoughtful design. All sessionโ€‘specific dataโ€”including checkpoint information, message history caches, and media download logsโ€”are stored under a structured directory tree: ///. The grow_checkpoint.json file records the last processed timestamp or message ID for each contact, enabling incremental operations such as โ€œfetch new messages since last runโ€ without reโ€‘scanning the entire chat. Meanwhile, history_bubbles.json holds a compact representation of the conversation that has already been processed through the vision pipeline, allowing the library to quickly rebuild the chat view in memory when needed. Deleting these files is the supported way to reset a contactโ€™s state from scratch, which is useful when testing new features or recovering from a corrupted cache. This explicit separation of concerns makes it easy for users to back up, migrate, or audit their automation state without interfering with the Chrome profile or the WhatsApp Web session data stored elsewhere.

One of the more sophisticated capabilities offered by wavi-lib is visionโ€‘based message editing. When a user wants to amend a previously sent message, the library first scans the chat viewport (scrolling as necessary) for a bubble whose text matches a userโ€‘supplied fragment, ignoring case and accent variations. If exactly one matching ownโ€‘message is found and it is younger than fifteen minutes, wavi-lib triggers WhatsAppโ€™s builtโ€‘in edit dialog, populates it with the current message content, applies the fragmentโ€‘based transformation, and then verifies that the edited text matches the intended result before confirming the change. Should the search yield zero matches, multiple candidates, or a message outside the edit window, the operation aborts cleanly without touching the UI, leaving the chat untouched. This careful guardrail prevents accidental edits and ensures that the automation behaves predictablyโ€”a critical requirement for any system that modifies userโ€‘generated content in a live messaging environment.

Complementing editing, wavi-lib also supports visionโ€‘powered replying with quoting, a feature that mirrors the manual process of selecting a message, choosing โ€œReply,โ€ and typing a response. The algorithm begins by performing an OCR sweep of the visible chat area, scrolling up to four screens worth of content to increase the likelihood of locating the target message. It then searches for a bubble whose inner text (excluding any quoted portions) contains the supplied match string. When a unique match is found, the script rightโ€‘clicks the bubble, uses OCR to read the context menu, selects the โ€œReplyโ€ option, and confirms that the quote panel correctly displays the chosen message. The response text is then entered and sent, after which the library reโ€‘reads the chat to verify that both the quoted message and the new reply appear as expected. If the OCR step yields ambiguous matches, the tool lists them numerically and allows the caller to disambiguate via a –from sender filter or by specifying an –index N. Any failure at any stage triggers an Escape keypress to cancel the quote operation, ensuring that no partial UI state is left danglingโ€”a hallmark of robust automation design.

Media handling rounds out wavi-libโ€™s feature set with a thoughtful approach to preserving the fidelity of shared photos and videos. When tasked with downloading media from a chat, the library first opens the conversationโ€™s media viewer and positions it on the most recent item. It then walks backward through the collection using the leftโ€‘arrow key, capturing each photo directly from the viewerโ€™s blob imageโ€”which yields the original, uncompressed fileโ€”and each video by issuing range requests to WhatsAppโ€™s /stream/video endpoint, assembling the chunks into a complete MP4. Downloaded assets are saved under ///media/ with a filename that encodes the date, time, sender, and a contentโ€‘based hash, preventing collisions while preserving provenance. Accompanying each file is a sidecar media.json record that documents the senderโ€™s identifier, timestamp, byte size, and SHAโ€‘1 hash, enabling downstream processes to deduplicate or verify integrity. Importantly, the script checks the local media folder before initiating a download, skipping any file that already exists, which makes repeated runs efficient and idempotentโ€”an essential trait for cronโ€‘based backup or archival workflows.

Bringing all these pieces together, wavi-lib represents a mature, productionโ€‘grade toolkit for anyone seeking to automate WhatsApp Web responsibly and at scale. Its visionโ€‘first core mitigates the fragility of DOMโ€‘based scrapers, while selective DOM usage for navigation keeps interactions snappy. The careful Chrome lifecycle management, IndexedDBโ€‘aware safeguards, and explicit recovery procedures demonstrate a deep understanding of the underlying web appโ€™s transactional nature. Features like alias management, incremental state checkpointing, verified editing and quoting, and highโ€‘fidelity media download transform the library from a simple scriptable tool into a versatile platform for chatbots, customerโ€‘service assistants, dataโ€‘archiving pipelines, and even research bots that need to harvest publicโ€‘domain information from WhatsApp groups. As messaging platforms continue to tighten antiโ€‘abuse measures, solutions that respect the clientโ€™s operational boundariesโ€”like wavi-libโ€”will become increasingly valuable for legitimate automation use cases.

For developers and organizations looking to adopt wavi-lib, the path forward is clear and pragmatic. Begin by installing the package from PyPI within a Pythonโ€ฏโ‰ฅโ€ฏ3.11 environment, then run wavi connect to establish the persistent Chrome session and scan the QR code once. Define meaningful aliases for your contacts or groups in data/sessions/aliases.json to simplify command invocations. Leverage the builtโ€‘in CLI for adโ€‘hoc tasks such as fetching recent messages, sending replies, or downloading media, and consider wrapping wavi serve in a lightweight HTTP frontend if you need to trigger automations from external systems or chatops platforms. Always observe the safety guidelines: never issue raw CDP commands to the WhatsApp tab, rely on wavi reload for state refreshes, and treat any qr_needed signal as a prompt for human intervention. Periodically audit the stored state files (grow_checkpoint.json, history_bubbles.json, media.json) to ensure they remain within expected size bounds, and prune older checkpoints if longโ€‘term storage is a concern. By following these practices, you can harness wavi-libโ€™s visionโ€‘driven reliability to build WhatsAppโ€‘based automations that are both powerful and respectful of the platformโ€™s constraints.