Baileys connector
¶ Socket flaps are expected noise
Production has seen frequent 408 and 428 closes. Flapping alone is not an incident.
First checkLook for customer-visible impact, failed jobs, or missing follow-up state before escalating.
Operations
¶ Known Production Behaviors
Do not re-investigate these from zero. These are observed WhatsApp, Cloud API, connector, and linked-device behaviors that can look like incidents until the first production signals are checked.
WhatsApp realities
Device-dependent work
Transport limits
How to use this page
¶ Recognize the shape, then verify the signal
A known behavior is not a free pass to ignore a report. It is a shortcut to the right first question: is this expected production behavior, a new scope, or evidence that the old boundary changed?
MatchFind the behavior that resembles the report.
VerifyCheck channel type, device state, ids, timestamps, and queue or deploy signals.
EscalateOpen a fresh RCA only when the evidence no longer fits the known boundary.
Behavior catalog
¶ What production already taught us
Each behavior includes the operational reading: what it usually means and where to look before treating it as a regression.
Cloud API
¶ Some addresses cannot be sent through Graph
Cloud API cannot address @lid or @g.us and may fail silently.
First checkConfirm the recipient id and make sure routing goes through
services/transport.py.History and media
¶ Paired phones serve recovery work
History sweeps and media re-upload are served by the paired phone. Sleeping phones cause timeouts.
First checkVerify the phone is awake and reachable before diagnosing server-side media code.
Delivery timing
¶ Late arrivals can be offline queue flushes
Messages arriving hours late are usually WhatsApp offline queue flushes on reconnect.
First checkCompare message timestamps with reconnect events before treating delay as a fresh send failure.
Companion integrations
¶ Missing chats can be fan-out misses
WhatsApp multi-device fan-out can miss chats when multiple companion integrations share one number.
First checkIdentify every companion integration attached to the number before assuming ReplyBox dropped the chat.
Linked device deletion
¶ Delete-for-me never reaches ReplyBox
Delete-for-me on a linked device is local to that device and never reaches ReplyBox.
First checkAsk whether the action was delete-for-me or delete-for-everyone before searching ingestion paths.
Sender attribution
¶ Linked-phone sends are indistinguishable
A message sent from a linked phone is indistinguishable from one sent by another device unless it came from ReplyBox.
First checkUse ReplyBox-created evidence when it exists; otherwise avoid promising a device-level sender.
Boundary rule
¶ Known does not mean ignored
These behaviors stop duplicate investigations, but they do not override new evidence. Reopen the question when the scope, channel, or timeline no longer matches the documented pattern.
Expected: repeated 408/428 socket closes with no failed work or customer-visible defect.
Investigate: the same flaps line up with missing sends, lost media, or tenant-specific data drift.
Expected: Cloud API cannot deliver to
@lid or @g.us.
Investigate: transport routing claims Baileys but delivery still follows Cloud API behavior.
¶ Record the match
When closing a report as a known behavior, write the matched behavior, channel type, timestamps, and the signal that ruled out a product defect.
¶ Link the deeper guide
Route stuck sends, Cloud API address failures, connector CPU, and media recovery to their focused operations pages once the symptom is identified.
¶ Update this page when the boundary changes
If production teaches a sharper rule, edit the behavior in place so future triage starts from the newest durable fact.