#21309: feat(telegram): support outbound media groups (albums) via sendMediaGroup
channel: telegram
size: M
Cluster:
Messaging Platform Improvements
## Summary
- When a reply contains 2–10 media items that are **all photos or videos** (no gifs, audio, or documents), send them as a Telegram album via `bot.api.sendMediaGroup()` instead of individual `sendPhoto`/`sendVideo` calls
- Only the first item carries the caption (Telegram displays it as the shared album caption)
- Mixed media (containing gifs, audio, or documents) falls back to the existing single-item send path — zero behavior change for non-groupable content
- When caption exceeds Telegram's 1024-char limit, the overflow text is sent as a follow-up message (reuses existing `splitTelegramCaption` logic)
- Inline buttons are sent as a follow-up message since `sendMediaGroup` does not support `reply_markup`
## Motivation
Closes #13620
Closes #14027
Currently the outbound path always sends media one at a time, even when the agent produces multiple images in a single response (e.g. image generation tools). Telegram's `sendMediaGroup` API groups 2–10 photos/videos into a single album message, which is much cleaner for the end user.
Note: OpenClaw already handles **inbound** media groups correctly (via `mediaGroupBuffer` in `bot-handlers.ts`). This PR fills the outbound gap.
## Changes
- `src/telegram/bot/delivery.ts`: Add media-group detection and `sendMediaGroup` call path before the existing single-item loop; import `InputMediaBuilder` from grammY
- `src/telegram/bot/delivery.test.ts`: Add 5 test cases covering album send, mixed photo+video, gif fallback, audio fallback, and single-image non-grouping; update grammY mock to include `InputMediaBuilder`
## Commits
- `1c4036e` feat(telegram): support outbound media groups (albums) via sendMediaGroup
## Validation
```
pnpm vitest src/telegram/bot/delivery.test.ts
```
16 tests pass (5 new + 11 existing).
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Adds Telegram media group (album) support for outbound messages containing 2-10 photos/videos. When all media items are groupable (photos or videos, no gifs/audio/documents), they're sent via `sendMediaGroup` as a single album instead of individual messages. The implementation correctly falls back to single-item sends for mixed content, handles caption overflow via follow-up messages, and sends inline buttons separately since `sendMediaGroup` doesn't support `reply_markup`.
- Introduces media groupability check before attempting album send (photos and videos only, no gifs)
- Reuses existing `splitTelegramCaption` logic for handling 1024-char caption limits
- Comprehensive test coverage including album sends, mixed photo/video, and fallback scenarios for gifs and audio
- Clean integration with existing single-item send path as fallback
<h3>Confidence Score: 5/5</h3>
- This PR is safe to merge with minimal risk
- The implementation is well-designed with comprehensive test coverage (5 new tests covering all major code paths), clean fallback behavior, and proper integration with existing caption/button handling logic. The code correctly handles edge cases (gifs, audio, single media), reuses proven utilities, and maintains backward compatibility by falling back to the existing single-item send path for non-groupable content.
- No files require special attention
<sub>Last reviewed commit: 1c4036e</sub>
<!-- greptile_other_comments_section -->
<sub>(2/5) Greptile learns from your feedback when you react with thumbs up/down!</sub>
<!-- /greptile_comment -->
Most Similar PRs
#14057: feat(telegram): add ignoreMediaTypes config to skip specific inboun...
by pavelsamoylenko · 2026-02-11
81.0%
#22434: feat(telegram): support sending original quality images
by godenjan · 2026-02-21
78.6%
#21898: fix(telegram): auto-detect captionable messages for editMessageCaption
by ptrkstr · 2026-02-20
78.2%
#13961: fix(telegram): support media attachments in replied Telegram messages
by shan-mx · 2026-02-11
77.3%
#15467: feat(messages): add debounceMedia option for inbound debouncing
by tangcruz · 2026-02-13
76.8%
#7261: fix(telegram): preserve DM topic thread id for outbound media
by ViffyGwaanl · 2026-02-02
76.4%
#20594: feat(whatsapp): batch multi-image messages via debouncer
by arniesaha · 2026-02-19
76.2%
#7902: feat: Implement Telegram video note support with tests and docs
by thewulf7 · 2026-02-03
76.1%
#19399: telegram: fix MEDIA false positives and partial final drop
by HOYALIM · 2026-02-17
76.1%
#8042: feat(telegram): add media index for reply-to media lookup
by batumilove · 2026-02-03
76.0%