#8479: feat(telegram): extract animation/GIF metadata & support animated/video stickers
channel: telegram
stale
## Summary
Two improvements to Telegram media handling for better agent context:
### 1. Animation/GIF metadata extraction
When users send GIFs/animations via Telegram, agents previously received a UUID-based filename (e.g. `file_12---48317467-8e25-4ba9-8b89-56230dbc3e05.mp4`) with no semantic context.
This extracts Telegram's native animation metadata (especially `file_name`, which often contains search terms like `thumbs-up.mp4`, `like-awesome.mp4`) and passes it through to the agent context.
### 2. Animated/video sticker passthrough
Previously, animated (TGS) and video (WEBM) stickers were **silently dropped** β `resolveMedia()` returned null, and the entire message was skipped. This is a significant UX issue since most modern Telegram stickers are animated.
Now, animated/video stickers return a metadata-only result (no media download) containing emoji + setName, formatted as `[Sticker π from "UtyaDuck"]` so agents can understand the sticker's intent.
## Changes
**Animation/GIF metadata:**
- `src/telegram/bot/types.ts` β New `AnimationMetadata` interface
- `src/telegram/bot/delivery.ts` β Handle `msg.animation` separately in `resolveMedia()`
- `src/telegram/bot-message-context.ts` β Format GIF placeholder as `<media:gif "filename">`
- `src/telegram/bot-handlers.ts` β Pass `animationMetadata` through handler pipelines
**Animated/video sticker support:**
- `src/telegram/bot/delivery.ts` β Return metadata-only for animated/video stickers instead of null
- `src/telegram/bot-handlers.ts` β Don't skip sticker messages that have metadata resolved
- `src/telegram/bot-message-context.ts` β Format metadata-only stickers with emoji/setName context
## Before/After
**GIF:**
| | Before | After |
|---|---|---|
| Agent sees | `file_12---uuid.mp4` | `<media:gif "thumbs-up.mp4">` |
| Understanding | Requires ffmpeg + vision model | Instant from file_name |
**Animated Sticker:**
| | Before | After |
|---|---|---|
| Agent sees | *(nothing β message dropped)* | `[Sticker π from "UtyaDuck"]` |
| Understanding | Impossible | Instant from emoji + set context |
## Testing
Tested in production with various media types:
- Telegram inline GIF search β file_name contains search terms β
- Forwarded GIFs β file_name preserved β
- Animated stickers (TGS) β emoji + setName passed through β
- Video stickers (WEBM) β emoji + setName passed through β
- Static stickers β unaffected (existing code path) β
Most Similar PRs
#13278: feat(telegram): full sticker support β thumbnail fallback, set inde...
by thebtf Β· 2026-02-10
76.2%
#19056: feat(inbound-meta): expose sticker metadata in system prompt
by xuandung38 Β· 2026-02-17
74.3%
#7502: feat(whatsapp): send WebP files as stickers
by giannisanni Β· 2026-02-02
71.8%
#6516: feat(telegram): add sticker and custom emoji vision support
by Shabablinchikow Β· 2026-02-01
69.4%
#19592: feat(whatsapp): add sendAsSticker support
by qualiobra Β· 2026-02-18
68.9%
#18915: fix(telegram): pass video width/height to sendVideo to prevent portraβ¦
by storyarcade Β· 2026-02-17
63.4%
#21309: feat(telegram): support outbound media groups (albums) via sendMedi...
by smysle Β· 2026-02-19
63.1%
#14057: feat(telegram): add ignoreMediaTypes config to skip specific inboun...
by pavelsamoylenko Β· 2026-02-11
62.9%
#13961: fix(telegram): support media attachments in replied Telegram messages
by shan-mx Β· 2026-02-11
62.5%
#22113: feat: support non-image file attachments in webchat chat.send
by Kt-L Β· 2026-02-20
62.1%