Skip to content

feat: add text debounce batching for WhatsApp and WeChat platforms - #35302

Closed
redpiggy-cyber wants to merge 1 commit into
NousResearch:mainfrom
redpiggy-cyber:feat/text-debounce-whatsapp-weixin-clean
Closed

feat: add text debounce batching for WhatsApp and WeChat platforms#35302
redpiggy-cyber wants to merge 1 commit into
NousResearch:mainfrom
redpiggy-cyber:feat/text-debounce-whatsapp-weixin-clean

Conversation

@redpiggy-cyber

Copy link
Copy Markdown
Contributor

Closes #35301

Summary

WhatsApp and WeChat (Weixin/iLink) deliver messages individually without client-side batching. Rapid multi-message bursts each trigger a separate agent invocation, wasting tokens and degrading UX.

This PR adds text-debounce batching to both adapters, mirroring the pattern already used by the Telegram, WeCom, and Feishu adapters.

Changes

gateway/platforms/whatsapp.py (+78 / -1)

  • Added _text_batch_delay_seconds, _text_batch_split_delay_seconds, _pending_text_batches, _pending_text_batch_tasks to __init__
  • Modified _poll_messages() to route TEXT messages through _enqueue_text_event() instead of directly calling handle_message()
  • Added _text_batch_key(), _enqueue_text_event(), _flush_text_batch() methods

gateway/platforms/weixin.py (+87 / -8)

  • Added batch attributes to __init__
  • Added batch cleanup in disconnect()
  • Modified _process_message() to route TEXT messages through debounce
  • Added _text_batch_key(), _enqueue_text_event(), _flush_text_batch() methods

Configuration (env vars)

Variable Default Description
HERMES_WHATSAPP_TEXT_BATCH_DELAY_SECONDS 5.0 Base delay before flushing WhatsApp text batch
HERMES_WHATSAPP_TEXT_BATCH_SPLIT_DELAY_SECONDS 10.0 Extended delay when near split threshold
HERMES_WEIXIN_TEXT_BATCH_DELAY_SECONDS 3.0 Base delay before flushing WeChat text batch
HERMES_WEIXIN_TEXT_BATCH_SPLIT_DELAY_SECONDS 5.0 Extended delay when near split threshold

Behavior

  • Only TEXT messages are batched — commands, media, and other types dispatch immediately
  • Messages are aggregated per session (DM or group chat)
  • The flush timer resets on each new message, so the batch dispatches only after the quiet period expires
  • When a chunk is near the platform's character limit, a longer split delay is used to wait for continuation fragments

WhatsApp and WeChat (Weixin/iLink) both deliver messages individually
without any client-side batching, so rapid multi-message bursts (forwarded
batches, paste-splits, etc.) each trigger a separate agent invocation.

This wastes tokens (redundant system prompts / context for each fragment)
and degrades UX (the user receives reply fragments instead of a single
coherent response).

Both adapters now mirror the Telegram adapter's proven text-debounce
pattern:

- _text_batch_delay_seconds / _text_batch_split_delay_seconds
  (configurable via env vars)
- _pending_text_batches dict for per-session aggregation
- _enqueue_text_event() concatenates successive TEXT messages and
  resets the flush timer
- _flush_text_batch() dispatches after the quiet period expires

Configurable via env vars:
  HERMES_WHATSAPP_TEXT_BATCH_DELAY_SECONDS (default 5.0)
  HERMES_WHATSAPP_TEXT_BATCH_SPLIT_DELAY_SECONDS (default 10.0)
  HERMES_WEIXIN_TEXT_BATCH_DELAY_SECONDS (default 3.0)
  HERMES_WEIXIN_TEXT_BATCH_SPLIT_DELAY_SECONDS (default 5.0)
@alt-glitch alt-glitch added type/feature New feature or request comp/gateway Gateway runner, session dispatch, delivery platform/whatsapp WhatsApp Business adapter platform/wecom WeCom / WeChat Work adapter P2 Medium — degraded but workaround exists labels May 30, 2026
@alt-glitch

Copy link
Copy Markdown
Collaborator

Related to #17165 (WhatsApp-only debounce, already open) and #22602 (feature request). This PR covers both WhatsApp and WeChat — if merged, would supersede #17165.

@teknium1

Copy link
Copy Markdown
Contributor

Merged via PR #35391 (commit cddb728). Your debounce commit was cherry-picked onto current main with your authorship preserved in git log (b0ce47d).

One change on top of your work: per our ".env is for secrets only / no new HERMES_* for behavior" policy, the batch delays are now read from config.yaml under gateway.platforms.{whatsapp,weixin}.extra.text_batch_delay_seconds / text_batch_split_delay_seconds instead of env vars, with a finite/non-negative guard. Tests + docs added for both adapters. Thanks for the contribution!

#35391

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

comp/gateway Gateway runner, session dispatch, delivery P2 Medium — degraded but workaround exists platform/wecom WeCom / WeChat Work adapter platform/whatsapp WhatsApp Business adapter type/feature New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

WhatsApp and WeChat forward multiple messages without debounce, wasting tokens and degrading UX

3 participants