Media Albums

Coalesce a Telegram media album into a single multimodal agent turn

Set one config knob and a Telegram media album — several photos or files sent together — becomes one multimodal agent turn instead of one turn per part.

A user taps three receipt photos, hits Send once, and the agent sees all three attachments in a single turn — so it can compare them.

from praisonaiagents import Agent
from praisonai.bots import Bot, BotConfig

agent = Agent(
    name="Receipt Reviewer",
    instructions="Compare the receipts the user sends and highlight the highest total.",
)

bot = Bot(
    "telegram",
    agent=agent,
    config=BotConfig(
        token="YOUR_BOT_TOKEN",
        metadata={"media_group_window_ms": 1200},  # enable album coalescing
    ),
)
bot.run()

Quick Start

1. Enable album coalescing

   Set media_group_window_ms on BotConfig.metadata to switch coalescing on. 0 (the default) keeps every album part as its own turn.

   from praisonaiagents import Agent
   from praisonai.bots import Bot, BotConfig
   
   agent = Agent(
       name="Receipt Reviewer",
       instructions="Compare the receipts the user sends.",
   )
   
   bot = Bot(
       "telegram",
       agent=agent,
       config=BotConfig(
           token="YOUR_BOT_TOKEN",
           metadata={"media_group_window_ms": 1200},  # 1200 ms silence = flush
       ),
   )
   bot.run()

2. Tune the album size cap

   Add media_group_max to bound how many attachments buffer per album before a forced flush. The default (10) covers a full Telegram album.

   bot = Bot(
       "telegram",
       agent=agent,
       config=BotConfig(
           token="YOUR_BOT_TOKEN",
           metadata={
               "media_group_window_ms": 1200,
               "media_group_max": 6,  # split larger albums into multiple turns
           },
       ),
   )
   bot.run()

How It Works

Telegram delivers each album part as its own update sharing one media_group_id. The coalescer buffers the parts and flushes them once, after a short window of silence.

Exactly one caller per group receives the MergedAlbum; sibling handle_message calls return None because their media was folded into the owner’s turn. A standalone (non-album) message has no media_group_id, so it returns its own parts immediately — no debounce added.

Configuration Options

Both knobs live on BotConfig.metadata (passthrough — there are no dedicated BotConfig fields).

Common Patterns

Compare several images in one turn:

agent = Agent(
    name="Receipt Reviewer",
    instructions="Compare the receipts the user sends and highlight the highest total.",
)
# User: sends 3 receipt photos as one album, caption "which is highest?"
# Agent sees one turn with 3 attachments → "Receipt #2 has the highest total: $84.20."

Split very large albums into multiple turns by lowering the cap:

bot = Bot(
    "telegram",
    agent=agent,
    config=BotConfig(
        token="YOUR_BOT_TOKEN",
        metadata={"media_group_window_ms": 1200, "media_group_max": 4},
    ),
)
# An album of 9 photos is delivered as turns of 4, 4, then 1.
bot.run()

Best Practices

Related