Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(pacing): count Baileys product sends into the daily cap
Yudhi Armyndharisc4d6bce43c2f
diff --git a/.env.example b/.env.exampleindex 1fa77c595..323a684e9 100644--- a/.env.example+++ b/.env.example@@ -241,12 +241,13 @@ OPENWA_PIDS_LIMIT=2048# brand-new WhatsApp account that immediately sends at volume is the pattern that gets numbers# banned. Any malformed entry falls the WHOLE schedule back to the default rather than sending more# than you asked for. Counts come from the messages table, so they survive a restart — but that also-# means the cap only sees sends that WRITE a row there. Status posts, message edits and Baileys-# product sends are real outbound traffic that persists no new row, so they pass through the check+# means the cap only sees sends that WRITE a row there. Status posts and message edits are real+# outbound traffic that persists no new row, so they pass through the check# without being counted — and so does a bulk item the engine refuses, because bulk writes its row# only after the send succeeds. A session doing any of them can exceed its stated daily allowance.# A bulk item that SUCCEEDS is counted, as is a failed single send, whose PENDING row is kept as-# FAILED.+# FAILED. A Baileys product send is counted once its own-send echo writes the outgoing row, shortly+# after the send returns, so a tight burst can pass the check before those rows land.# SEND_PACING_ENABLED=true# SEND_PACING_WARMUP_SCHEDULE=20,40,80,160,320,640,1000#diff --git a/docs/06-api-specification.md b/docs/06-api-specification.mdindex 1120e38cb..f90b5274f 100644--- a/docs/06-api-specification.md+++ b/docs/06-api-specification.md@@ -1561,11 +1561,11 @@ extra work is done.When enabled, three rules can refuse a send:-| Rule | What it means |-| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| Warm-up daily cap | The session has used its allowance for the current **UTC** day. The allowance grows with the session's age (`SEND_PACING_WARMUP_SCHEDULE`), because a brand-new WhatsApp account that immediately sends at volume is the pattern that gets numbers banned. The count comes from the messages table, so it survives restarts — and so it only sees sends that write a row there. Status posts, message edits and Baileys product sends are checked against the cap but never counted into it — none of them writes a row, and an edit only updates one — and neither is a bulk item the engine refuses, because bulk persists its row only after the send succeeds. A session using any of them can exceed its stated allowance. A bulk item that succeeds is counted, as is a failed single send, whose PENDING row is kept as FAILED. |-| Cold-reachout cap | The session has used its allowance of **new conversations** for the UTC day (`SEND_PACING_COLD_DAILY_CAP`). A send is a cold reachout when the account has no history with that chat in **either** direction — replying to someone who wrote to you first is never counted, and never refused by this rule. Status posts address no chat and are exempt. |-| Failure breaker | Consecutive send failures reached `SEND_PACING_BREAKER_THRESHOLD`, which usually means WhatsApp has already started refusing this account. The streak has no time decay — only a successful send resets it, so failures spread across a long quiet period still accumulate toward the threshold. Sends resume after `SEND_PACING_BREAKER_COOLDOWN_MS`, or immediately after any send succeeds. |+| Rule | What it means |+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| Warm-up daily cap | The session has used its allowance for the current **UTC** day. The allowance grows with the session's age (`SEND_PACING_WARMUP_SCHEDULE`), because a brand-new WhatsApp account that immediately sends at volume is the pattern that gets numbers banned. The count comes from the messages table, so it survives restarts — and so it only sees sends that write a row there. Status posts and message edits are checked against the cap but never counted into it (a status post writes no row, and an edit only updates one), and neither is a bulk item the engine refuses, because bulk persists its row only after the send succeeds. A Baileys product send writes no row itself: it is counted once its own-send echo writes the outgoing row, shortly after the send returns, so a burst can pass the check before those rows land, and a product send into a disappearing-messages chat is not counted at all when `STORE_EPHEMERAL_MESSAGES=false`. A session using any of them can exceed its stated allowance. A bulk item that succeeds is counted, as is a failed single send, whose PENDING row is kept as FAILED. |+| Cold-reachout cap | The session has used its allowance of **new conversations** for the UTC day (`SEND_PACING_COLD_DAILY_CAP`). A send is a cold reachout when the account has no history with that chat in **either** direction — replying to someone who wrote to you first is never counted, and never refused by this rule. Status posts address no chat and are exempt. |+| Failure breaker | Consecutive send failures reached `SEND_PACING_BREAKER_THRESHOLD`, which usually means WhatsApp has already started refusing this account. The streak has no time decay — only a successful send resets it, so failures spread across a long quiet period still accumulate toward the threshold. Sends resume after `SEND_PACING_BREAKER_COOLDOWN_MS`, or immediately after any send succeeds. |A refusal is `429` with a body carrying **`code: "SEND_PACING_LIMITED"`** and `retryAfterSeconds`:diff --git a/docs/16-risk-management.md b/docs/16-risk-management.mdindex 1252ab7ec..fb24b5ac6 100644--- a/docs/16-risk-management.md+++ b/docs/16-risk-management.md@@ -126,8 +126,8 @@ Opt-in: `SEND_PACING_ENABLED=true` adds a per-UTC-day send cap whose allowance gsession's age (`SEND_PACING_WARMUP_SCHEDULE`), a separate cap on new conversations(`SEND_PACING_COLD_DAILY_CAP`) and a consecutive-failure breaker — see[06 §Send pacing](./06-api-specification.md). It is **off by default**, and it counts only sends that-write a `messages` row, so status posts, catalog sends and message edits are checked against the cap-without counting into it.+write a `messages` row, so status posts and message edits are checked against the cap without+counting into it.Still not implemented: there are no per-minute or per-hour caps and no media-specific delay. Withpacing off — the default — the guidelines below are operator discipline, not something the gatewaydiff --git a/src/modules/message/send-pacing.service.ts b/src/modules/message/send-pacing.service.tsindex 0e106fcf8..05342dd02 100644--- a/src/modules/message/send-pacing.service.ts+++ b/src/modules/message/send-pacing.service.ts@@ -106,13 +106,15 @@ const MAX_REFUSAL_KEYS = 1000;* already the durable record of every chat send — bulk included, which persists through the same* `saveOutgoingMessage` — and it already carries the `(sessionId, createdAt)` index the count needs.* So the cap survives restarts with no table and no migration. The trade is that it counts only what- * writes a row. Three kinds of path clear this check without ever adding to it: a status post- * (status.service.ts), both Baileys catalog sends (catalog.service.ts `sendProduct` and- * `sendCatalog`), and a message edit — which is gated here via applySendingGate but only UPDATEs the- * existing row, never inserts. A bulk item the engine refuses is a fourth: bulk persists its row only+ * writes a row. Two kinds of path clear this check without ever adding to it: a status post+ * (status.service.ts) and a message edit, which is gated here via applySendingGate but only UPDATEs+ * the existing row, never inserts. A bulk item the engine refuses is a third: bulk persists its row only* after the send succeeds, so a failed item is checked against the cap but never counted into it,* unlike a failed single send whose PENDING row is kept as FAILED. A session using- * them can exceed its stated allowance. Deliberate, and documented in .env.example and docs/06 so+ * them can exceed its stated allowance. A Baileys product send (catalog.service.ts `sendProduct`)+ * writes no row itself but is counted through the OUTGOING row its own-send echo persists+ * (MessageProjector.handleOwnSendEcho) shortly after the send returns; sendCatalog answers 501 on+ * both engines. Deliberate, and documented in .env.example and docs/06 so* the number an operator reads is the number they get.* The breaker, by contrast, is in memory on purpose: it describes live conditions, and a restart* clearing it is the correct behaviour.