Build notes › topic

Reliability

One failure wearing different clothes: something reporting success for work it had not done. What each one quietly cost, and the checks added so the next one fails loudly.

Covered here: self-deployed WhatsApp CRM · 7-star customer experience · agent-eval v1.0 · AI contact enrichment · catalog_management scope · catalogue sync · Cloudflare Queues dead letter queue · Cloudflare Worker voice AI agent · consent keyword collision · consent management

• 3 September 2026 · reliability & consent

  The WhatsApp quiet hours that were loudest at 3am

  Every regulation that defines quiet hours defines them at the called party’s location. Ours compared against getUTCHours(), which is the server’s idea of the time and nobody else’s. For an Indian recipient a 21:00 to 08:00 window silenced sending from 02:30 to 13:30 their time, which is most of a working day, and cheerfully permitted it at 03:00 local. Not merely wrong: exactly inverted, and worse the further a deployment sits from Greenwich. This note covers why a hardcoded offset table is the wrong fix, why an unknown timezone must fail open rather than silence somebody, and the second half of the same commit: Meta’s per-user marketing cap, which we knew about, excluded from campaigns, and had never applied to the lifecycle senders that walked straight into it.

• 3 September 2026 · platform & migration

  What survives when you move to the official WhatsApp API

  The most-asked question about leaving an unofficial WhatsApp library is whether you lose your history, and most answers to it are wrong in the flattering direction. Verified against our own sync code rather than asserted: contacts, groups and memberships transfer, in batches of 500, idempotently, and can be re-run safely. Conversation history does not transfer at all, because Meta does not permit importing prior conversations into the Cloud API, and no vendor can work around a restriction that lives on Meta’s side. This note documents exactly which fields survive, why the history limit is structural rather than a missing feature, what an empty thread costs an agent on day one, and the one thing worth doing in the fortnight before you switch.

• 3 September 2026 · reliability & platform

  The WhatsApp broadcast that quietly lost its tail

  Every HTTP client is taught the same rule: 4xx is your fault, do not retry; 429 and 5xx are transient, back off and try again. Meta breaks it. The WhatsApp Cloud API returns its throughput caps, 130429, 131048 and 131056, as ordinary 4xx rather than 429, so a correct implementation of that rule permanently fails every message caught by a cap that would have cleared on its own within the hour. On a broadcast that means the back half of the send is discarded and marked failed while the front half delivered, and nothing in the response says a cap was involved. Documents the three codes, why the failure is invisible, the classifier that fixed it, and the free CC-BY dataset of every code we document, with their retry semantics, generated from the classifier that actually runs on our send path.

• 3 September 2026 · reliability & platform

  The WhatsApp session that logged itself out 377 times

  A WhatsApp Web session that regenerated QR codes 377 times in one night, and the process leak underneath it. Killing a Chromium without confirming it had died left eleven of them alive at once, every one holding the same LocalAuth directory, every one invoking takeoverOnConflict against the others, until WhatsApp did the only sensible thing and logged the device out. The logout was not Meta detecting automation. It was our own zombies fighting over one auth directory. Documents the full cascade, why SIGKILL is not a kill, and the three fixes: a verified kill that polls until the PIDs are actually gone, a per-session lifecycle mutex so a teardown always completes before the next spawn, and a relink policy that parks a session instead of regenerating QR codes unattended for hours.

• 1 September 2026 · AI evaluation & reliability

  Engineering Klaros AI WhatsApp Agent with Diligent Evaluation

  Nuts and Bolts of Building a Production Grade Voice and Text Product Orchestrator. How we moved from basic prompt engineering to an enterprise-grade evaluation harness (agent-eval v1.0), F0-F5 Cloudflare infrastructure fidelity, micro-confidence voice safeguards (<0.70 handoff), synthetic mutation testing (20/20 detected), and an 8-step controlled rollout protocol (0% to 100%) backed by canonical RFC 8785 JCS SHA-256 evidence.

• 28 August 2026 · commerce

  Building a WhatsApp catalogue that tells the truth

  Meta's catalogue batch endpoint returns HTTP 200 even when every item was rejected. The script we wrote specifically to verify a token could write reported success against a catalogue that was empty and had always been empty. Eleven bugs from three weeks of building catalogue and product infrastructure, almost all of the same shape: something reporting success for work it had not done. Includes a paywall that only worked while the feature was switched off, a complete edit endpoint with no button behind 5,187 passing tests, and the two calls we got wrong ourselves.

• 19 August 2026 · updated 21 August 2026 · AI architecture & roadmap

  Klaros WhatsApp Autonomous AI Agent: To-Be Architecture for a 7-Star Experience

  A candid developer architectural roadmap challenging our own past design decisions, now carrying a correction. The hybrid sparse-dense retrieval this note proposed had already been written and registered ahead of every other strategy, and it had never executed once: the Cloudflare Vectorize binding it depended on does not exist on the worker, so every request took its fallback branch and re-served plain BM25 while reporting success. The audit that found it also found the real defect, which was more mundane and worse: ingest deletes the 173 question-and-answer pairs the site publishes in its own structured data, then asks a ranking function to reconstruct them from the prose. Dense retrieval is deferred in favour of contextual BM25 and reranking.

• 13 August 2026 · conversational AI

  The WhatsApp auto-reply that answered a hello with a price list

  A contact of five weeks typed “Hello” and received an explanation of our licensing. The model was not hallucinating: the thread query selected the oldest 40 rows of a 46-message conversation, so it was shown messages 21 to 40 and never saw the greeting it was answering. Every timestamp had been stripped too, so a pricing exchange from three weeks earlier read as the previous turn. Investigating one bad reply surfaced seven more ways the same assistant was failing to listen, including voice notes answered with total silence, “cancel my order” recorded as an unsubscribe, and a customer who asked to speak to a person and was ignored twice.

• 10 August 2026 · performance

  The WhatsApp inbox skeleton that made things worse

  Shimmer skeleton loaders replaced stale content during WhatsApp conversation filter switches. But loadConversations() was a zero-argument function called from 30 sites, including the background poll that checks for new webhook deliveries. The skeleton fired on every poll, flashing every 5 seconds, but only on inboxes smaller than the page size: exactly the state a shop starts in after completing Meta's Embedded Signup. The fix was one parameter: 9 user-initiated call sites pass { skeleton: true }; the ~20 incremental updates (resolving, assigning, sending templates) and the poll do not.

• 8 August 2026 · consent

  The WhatsApp opt-out that almost got a sales pitch

  We sell Klaros inside a WhatsApp thread, which puts our own sales code in the same inbound path that decides whether somebody's opt-out gets recorded. The pricing intent matches pricing; "stop sending me pricing" contains it. And because a handled sales message suppresses the consent check, losing that fight would not have meant a tactless reply. It would have meant the opt-out was never recorded at all. The guard, the same rule applied four times, and the gap we found while writing this: a politely worded opt-out is still heard by nobody.

• 7 August 2026 · engineering

  The WhatsApp business cards that started asking for money

  Two features wanted the same short URL prefix, and the newer one was mounted first. For five days, scanning any of our free digital business cards returned "This payment link is not valid." Why neither route could move (one URL is fixed inside an approved Meta template, the other is printed on paper), the three-line fallthrough that fixed it, the passing test that was quietly asserting the bug, and the telemetry blind spot that means we can never count who saw it.

• 6 August 2026 · engineering

  The WhatsApp contacts we silently stopped scoring

  Our own health check found 68 dead-lettered enrichment messages, 100% one type, lined up exactly with two nights of the nightly cron. The cause was three UPDATE statements writing to a graph_contacts column that never existed. What broke, what it quietly cost every contact that should have been scored, and the regression tests we proved could catch the bug before trusting them, by reintroducing it first.

• 31 July 2026 · engineering

  The WhatsApp CRM billing we fixed before charging anyone

  A jeweller pays for three WhatsApp lines and silently receives one. She does not complain. She decides the software is small, and six weeks later she does not renew. That was a real defect in our code, and four others sat beside it, unnoticed because no money had ever moved through the system that held them. What we found in the room where the money moves, the two forks where the flattering answer lost, and the tool that now checks what we charge against what we publish.

• In progress

  The half of a sale that nobody demos

  Every platform shows you the payment landing. Almost none show you the twenty minutes afterwards: who gets told, who packs it, what the buyer hears while they wait, and what happens when it ships four days later and the messaging window has closed.

• In progress

  Where the ask ends and the shop begins

  A payment request is messaging machinery. A product library is a commerce application, and the part most likely to be replaced by a real one. On finding that seam in our own code, and making it a documented extension point instead of a function that happened to sit in the middle of a file.

• In progress

  What a feature looks like when nothing consumes it

  Contact limits computed on every request and enforced nowhere. A tier ladder that is marketing copy at runtime. On the difference between building a capability and shipping one, found in our own codebase.