openclaw - 💡(How to fix) Fix [Feature]: Telegram — expose mediaGroupTimeoutMs / mediaGroupFlushMs as a user-facing config key (follow-up to #1811) [1 comments, 2 participants]

Problem

The Telegram extension's media-group buffer flush window is hardcoded to 500ms and is only overridable via opts.testTimings.mediaGroupFlushMs, which is a test-only hook with no user-facing config path.

When network latency between Telegram's CDN and the gateway causes some album items to arrive >500ms after the first, the buffer flushes prematurely and the agent processes the message with partial media. Users see this as: "agent says it doesn't see the images, then if I wait, it processes them" — the agent reacts to the partial flush, then a second flush completes the rest.

This was originally reported as #1811 (closed as COMPLETED 2026-01-29) but the underlying constant is still hardcoded at 500ms in v2026.4.27, and the last comment on that thread reads "Still an issue for me!" — suggesting the closed-as-completed state didn't reflect a real fix, or a regression slipped in afterward.

Code reference (v2026.4.27)

dist/extensions/telegram/bot-Buo9I9xm.js:1159:

const mediaGroupTimeoutMs = typeof opts.testTimings?.mediaGroupFlushMs === "number"
  && Number.isFinite(opts.testTimings.mediaGroupFlushMs)
    ? Math.max(10, Math.floor(opts.testTimings.mediaGroupFlushMs))
    : 500;

The 500ms default is sensible, but there is no production-config path to raise it on slower networks.

Why messages.inbound.debounceMs doesn't cover this case

For completeness — inboundDebounceMs exists and is reachable via messages.inbound.debounceMs / messages.inbound.byChannel.telegram. But the default-lane shouldDebounce predicate in the same file (around line 1194) explicitly returns false for media-only messages without debounceable text:

if (!hasDebounceableText) return false;
return entry.allMedia.length === 0;

So pure-image albums (the most common multi-attachment case) bypass the inbound debouncer entirely and rely solely on the 500ms mediaGroupTimeoutMs. There is no current config knob that affects them.

Proposed solution

Expose mediaGroupTimeoutMs (or rename to mediaGroupFlushMs for parity with the test hook) as a user-facing key under the existing telegram channel config. Suggested location:

{
  "channels": {
    "telegram": {
      "mediaGroupFlushMs": 1500   // optional, default remains 500
    }
  }
}

Alternatively under messages.inbound.byChannel.telegram.mediaGroupFlushMs to colocate with the existing inbound-debounce settings.

Repro

1. Send a Telegram album of 4+ images (no caption) to an OpenClaw-bound bot from a mobile client on a slower network.
2. Observe the agent reply referencing fewer images than were sent, or "I don't see any images attached".
3. Wait — a follow-up reply (or visible buffer flush in journalctl --user -u openclaw-gateway-<profile>.service) shows the remaining images arriving after the first flush.

Workarounds today

• Adding a caption sometimes routes the message through paths that pick up the inbound debouncer (less reliable for media-only sends).
• Forking the package to patch the constant.

Neither is reasonable for production users. The fix is small (~5 lines: read from cfg with the existing 500ms as fallback).

Environment

• OpenClaw: 2026.4.27 (cbc2ba0)
• Channel: Telegram (DM, default lane)
• Symptom reproducible across multiple bots on the same gateway

cc #1811, related to #39343 (the Telegram half of that broader request would be resolved by this).