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:
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
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.