Periodic heartbeat checks against the paired phone will predict session death before auth tokens expire

Hypothesis

Periodic heartbeat checks against the paired phone will predict session death before auth tokens expire

Changelog

Date	Summary
2026-04-12	Initial creation

---

Hypothesis

The auto-recovery experiment solved transient disconnections but exposed a harder problem: auth token expiration after the paired phone goes offline for extended periods. WhatsApp Web revokes session tokens after approximately 14 hours of phone disconnection, but provides no warning. The hypothesis was that periodic heartbeat checks: probing the connection to the paired phone at regular intervals: could detect the phone-offline state hours before token expiration, giving the user time to bring the phone back online and avoid a full session death.

The key insight from the prior experiment was that the session does not die instantly when the phone goes offline. There is a grace period (observed at 12-16 hours) during which the web session remains valid but cannot send or receive new messages. If the system can detect this intermediate state, it can alert before the point of no return.

Method

The heartbeat system sends a lightweight probe every 5 minutes that tests three things: WebSocket connection alive, message send capability (sends a self-message), and phone sync status (checks last-seen timestamp from WhatsApp’s presence protocol). Each probe is classified as: healthy (all three pass), degraded (WebSocket alive but send fails or last-seen stale >30 min), or dead (WebSocket disconnected).

When the system enters degraded state for 3 consecutive probes (15 minutes), it triggers an alert via system notification. The alert includes the estimated time until token expiration based on the last known phone-online timestamp.

Testing ran for 21 days from late November through mid-December 2025. The paired phone was used normally (not artificially taken offline). All phone-offline events were organic: overnight airplane mode, dead battery, and travel through cellular dead zones.

Results

Over the 21-day period, the heartbeat system processed 6,048 probes (288 per day). It detected 8 phone-offline events, of which 5 were genuine extended offline periods (>2 hours) and 3 were brief cellular dead zones (<20 minutes).

For the 5 genuine offline events, the heartbeat alert fired an average of 6.2 hours before the estimated token expiration time. In all 5 cases, the user brought the phone back online after receiving the alert, and no auth re-scan was required. This represents a 100% prediction accuracy for genuine offline events with zero false negatives.

The 3 false positives occurred when the phone was in a cellular dead zone but still technically online (WiFi was available but the WhatsApp servers were unreachable from the phone’s perspective). The false positive rate of 37.5% (3 out of 8 detected events) is acceptable given that false positives only produce a notification, not a disruptive action.

Combined with the auto-recovery system from the previous experiment, the complete reliability stack now handles: transient disconnections (auto-recovery, 94% success), predicted session death (heartbeat alerts, 100% prediction for genuine events), and unexpected auth expiration (manual QR re-scan, now reduced to zero events during the test period).

Findings

1. The degraded state is reliably detectable. The gap between “WebSocket alive” and “messages actually flowing” is the signal. When the phone is offline, the web session stays connected to WhatsApp’s servers but cannot relay messages through the phone. This creates a distinct degraded signature.

2. 5-minute probe interval is the sweet spot. Testing with 1-minute intervals produced excessive noise from momentary network fluctuations. 15-minute intervals missed brief offline periods that could cascade into longer ones. 5 minutes balanced responsiveness with noise.

3. Self-message probe is the most reliable test. Presence protocol last-seen timestamps are cached and sometimes stale even when the phone is online. Actually sending a message and confirming delivery is the ground truth.

4. Cellular dead zones are indistinguishable from genuine offline. The system cannot differentiate “phone has no signal” from “phone is turned off” because both produce the same degraded heartbeat signature. Accepting false positives is the correct tradeoff.

Next Steps

With session reliability solved (auto-recovery + heartbeat monitoring), the next bottleneck was the deployment model itself. Running WhatsApp Web in a headless browser on a server is fragile and requires constant maintenance. The macOS native client experiment explored whether bridging directly to WhatsApp’s web interface via a native desktop app could eliminate the headless browser dependency entirely. See experiments/openclaw/2025-12-10-macos-web-chat-native-bridge.