Aug 2026Case studyIn production5 min read

WhatsApp Web chats into a CRM, without an API

Sales reps work leads in WhatsApp Web, and WhatsApp offers no API to get those chats into a CRM. I built a Chrome extension that reads WhatsApp Web's internal stores, syncs chats in the background without disturbing the rep, and stops rather than guesses when WhatsApp changes underneath it.

Reps' WhatsApp conversations never reached the CRM, and WhatsApp has no API for it. This extension syncs them in the background without touching the chat the rep has open.

JavaScript / Chrome Extensions (MV3) / Web Reverse Engineering

Challenge
Sales reps work in WhatsApp Web, and WhatsApp offers no API for reading those chats into a CRM.
Approach
A Manifest V3 extension that finds WhatsApp Web's internal chat store at runtime, resolves each contact to a phone number, and loads older history without switching the chat the rep has open.
Impact
Rep conversations reach the CRM without interrupting the rep. When WhatsApp ships a change the extension doesn't recognize, sync stops instead of guessing.
How a chat reaches the CRM
  1. 1Find the store

    The extension asks for WhatsApp Web's chat store by its exact internal module id.

  2. 2Fall back, or stop

    If WhatsApp renamed the module, a shape scan looks for it. If nothing matches, sync stops and shows no indicator rather than guess.

  3. 3Resolve the person

    Chats can carry privacy ids instead of phone numbers, so the number is resolved through the contact store before a CRM lead is created.

  4. 4Page history quietly

    Older messages are loaded straight from the store. The chat the rep has open never changes.

  5. 5Survive restarts

    Chrome can stop the extension at any moment, so nothing lives in memory: state is re-read from storage on every message.

Official API available
None: it reads WhatsApp Web's own internal stores
Rep's screen during sync
Unchanged, verified across a full history page

Problem

Sync a rep’s live WhatsApp Web conversations into a CRM with no official API for it, against an application that ships new minified bundles on its own schedule, inside an extension runtime that can kill your process between any two events, and never interrupt the rep while doing it.

Three constraints, each pulling a different way:

  1. No stable interface. Every symbol the extension depends on is internal to WhatsApp Web.
  2. No durable process. Manifest V3 terminates the service worker whenever it likes.
  3. No visible footprint. A sync that steals the rep’s active chat is worse than no sync.

Discovery: two tiers, deliberately

Diagram
resolvedid renamedmatchedno matchresolveStore(name)Tier 1exact module idStore handleTier 2shape scanFail closedno indicator

Tier 1 is one call and works before login. Tier 2 is the dashed path: a degradation route kept only for the rebuild that renames a module id, ending in a fail-closed state rather than a guess.

Tier 2 came first historically and was demoted for a reason. Shape matching asks “does this object have _models, modelClass, and notSpam?” And more than one thing does. The Chat matcher resolved the Newsletter collection; the Contact matcher resolved group metadata. The objects were the right shape and the wrong object, which no amount of tightening the predicate fixes reliably.

Tier 1 asks for the store by exact module id and gets it. Tier 2 stays in the codebase because the failure mode it covers is real: a WhatsApp rebuild that renames modules breaks tier 1 by definition, and a degraded-but-working path beats a hard stop.

A related bundler quirk cost time worth recording: after one WhatsApp build change, modules arrived double-wrapped for ESM interop as mod.default.default rather than mod.default, silently breaking matching. The resolution adds an unwrapped-shape candidate rather than picking which layer is “correct”. The bundle gets to change its mind.

Identity resolution

WhatsApp’s @lid privacy identity means the number read directly off a chat record is sometimes not a phone number. Resolution goes through the Contact store rather than trusting the chat, so a CRM lead is never created against a synthetic identifier.

Call history: the hypothesis that was wrong

The intuitive answer, WAWebCallCollection, is wrong in a way that only shows up after a call ends: it tracks the in-progress call and its history array empties immediately. The Calls tab is actually rendering ordinary chat messages with type === "call_log", which are already in memory because the chat list needs them for preview text, so call history is available before the Calls tab is ever opened, from a store that was already loaded. Neither whatsapp-web.js nor open-wa implement this.

The read path that stays out of the way

The earlier catch-up implementation opened a chat in the UI to sync it, which visibly switched the rep’s active chat mid-sync. WAWebChatLoadMessages.loadEarlierMsgs() pages history directly against the store instead, with no UI interaction at all, verified live by comparing Store.Chat.getActive() before and after a full history page and finding it identical.

That verification is the load-bearing part. “Should not affect the UI” is an assumption; “the active chat object is unchanged across a full page of history” is a check. Background catch-up now runs periodically for anyone who consented once, and still skips a chat while the rep is actively typing in it.

MV3 constraints as architecture

  • No in-memory state in the service worker. Chrome terminates it between events, so anything durable goes through chrome.storage.local and is re-read per message. State that lives in a variable is state that disappears.
  • One chrome.runtime.onMessage dispatcher keyed by message.type is the only cross-context entry point. The CRM auth key never leaves the background context, so a compromised or merely buggy content script on web.whatsapp.com cannot read it.
  • Two features are deliberately backendless. Follow-up reminders and the do-not-contact list run on chrome.alarms, chrome.notifications, and local storage only, shipped without waiting on backend capacity, and documented as that choice rather than pretending it was the ideal design.

Bugs closed in production logic

  • Same-second dedup. WhatsApp timestamps are per-second, so two messages can share one t. A “sync everything newer than X” check cannot distinguish already-synced from new-in-the-same-second. Fixed by tracking the specific message ids seen at the sync boundary alongside the timestamp.
  • Silent data loss in the outbox. A failed auto-sync batch was dropped the moment the next batch arrived. Failed batches now re-queue and drain on the following run.
  • A batch size that could wedge sync permanently. The bulk endpoint was assumed to accept 200 messages per call; the server caps at 50. Any account with more backlog than that would resend an oversized request that could never succeed. Fixed the constant and documented why it is not a tunable.

Failure policy

Every read of WhatsApp internals is one deploy away from being wrong, so the policy is fail-closed: if the chat-list ordering assumption breaks, the sync indicator renders nothing. No badge is safer than a wrong badge: a missing indicator is a support ticket, an indicator on the wrong contact is a data-integrity incident.

What the design pays for

Two tiers of discovery, an unwrapped-shape candidate, an identity indirection, and a fallback path that only runs when WhatsApp changes underneath it. That is the price of reading a live personal session with no official API, and it buys the property that matters: when WhatsApp ships a change, the extension degrades visibly and recovers, instead of syncing the wrong data.