- 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.
1Find the store
The extension asks for WhatsApp Web's chat store by its exact internal module id.
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.
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.
4Page history quietly
Older messages are loaded straight from the store. The chat the rep has open never changes.
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:
- No stable interface. Every symbol the extension depends on is internal to WhatsApp Web.
- No durable process. Manifest V3 terminates the service worker whenever it likes.
- No visible footprint. A sync that steals the rep’s active chat is worse than no sync.
Discovery: two tiers, deliberately
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.localand is re-read per message. State that lives in a variable is state that disappears. - One
chrome.runtime.onMessagedispatcher keyed bymessage.typeis the only cross-context entry point. The CRM auth key never leaves the background context, so a compromised or merely buggy content script onweb.whatsapp.comcannot 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.




