Inbound Media

Forward user photos and documents to your agent's vision capability across WhatsApp and Telegram

Bot adapters forward inbound photos and documents to your agent’s vision capability — validated, size-capped, and SSRF-safe.

from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="Describe photos and documents users send in chat.",
)

agent.start("What is in this image?")

The user sends a photo or document in WhatsApp or Telegram; the bot validates the file and passes it to the agent vision model.

Quick Start

1. Simple — works with any vision model

   No configuration needed. Point a vision-capable agent at your bot.

   from praisonaiagents import Agent
   from praisonai.bots import TelegramBot
   
   agent = Agent(
       name="vision-assistant",
       instructions="Describe images and answer questions about them.",
       llm="gpt-4o",
   )
   
   bot = TelegramBot(token="your-telegram-bot-token", agent=agent)
   
   import asyncio
   asyncio.run(bot.start())

   Send the bot a photo (with or without a caption). The agent sees the image and responds.

2. With size limit

   Cap media size for public-facing bots to avoid processing large files.

   from praisonaiagents import Agent
   from praisonai.bots import WhatsAppBot
   from praisonaiagents import BotConfig
   
   agent = Agent(
       name="assistant",
       instructions="Help users with their images and questions.",
       llm="gpt-4o",
   )
   
   bot = WhatsAppBot(
       agent=agent,
       config=BotConfig(
           max_inbound_media_bytes=5 * 1024 * 1024,  # 5 MiB cap
       ),
   )
   
   import asyncio
   asyncio.run(bot.start())

3. Disable inbound media

   Set max_inbound_media_bytes=0 for text-only agents.

   from praisonaiagents import Agent
   from praisonai.bots import TelegramBot
   from praisonaiagents import BotConfig
   
   agent = Agent(name="text-only", instructions="Answer text questions only.")
   
   bot = TelegramBot(
       token="your-token",
       agent=agent,
       config=BotConfig(max_inbound_media_bytes=0),
   )
   
   import asyncio
   asyncio.run(bot.start())

How It Works

Platform Coverage

Media Albums

Coalesce a burst of updates sharing one media_group_id into a single multimodal turn — the agent sees the whole album at once instead of N separate turns.

Opt in via BotConfig.metadata — disabled by default so existing deployments are unchanged.

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

agent = Agent(
    name="album-assistant",
    instructions="Compare and describe the photos the user sends.",
    llm="gpt-4o",
)

bot = TelegramBot(
    token="your-telegram-bot-token",
    agent=agent,
    config=BotConfig(
        metadata={
            "media_group_window_ms": 1200,   # silence window (0 = disabled)
            "media_group_max": 10,           # cap per album (default: 10)
        },
    ),
)

import asyncio
asyncio.run(bot.start())

Each inbound update flows through this decision path:

Behaviour

Configuration

Both album options live under BotConfig.metadata (there are no top-level BotConfig fields for them — resolve_album_window_ms / resolve_album_max_items read metadata first, then a direct attribute). Values that fail int() coercion silently fall back to the default.

Set via BotConfig:

from praisonaiagents import BotConfig

config = BotConfig(
    max_inbound_media_bytes=10 * 1024 * 1024,  # 10 MiB
)

Or via YAML:

agent:
  name: vision-bot
  instructions: Describe images.
  llm: gpt-4o

platforms:
  telegram:
    token: ${TELEGRAM_BOT_TOKEN}
    max_inbound_media_bytes: 10485760       # 10 MiB
    metadata:
      media_group_window_ms: 1200           # coalesce albums (0 disables)
      media_group_max: 10

Common Patterns

Photo + question (most common)

The user sends a photo with a caption asking a question. The caption becomes the prompt; the image is the attachment.

User: [photo of a chart] → "What does this chart show?"
Agent: "The chart shows quarterly revenue growth from Q1 to Q4..."

Document analysis

Send a PDF or Word document. The agent reads the content via vision.

User: [report.pdf] → "Summarize the key findings"
Agent: "The report covers three main findings..."

Oversized file rejected

Files above max_inbound_media_bytes are silently dropped. Only the caption text is forwarded.

User: [50 MB video] → "Describe this"
Agent: (receives only "Describe this", no attachment)

Non-vision agent (backward compatible)

If agent.chat() does not accept attachments, the adapter skips the file gracefully.

agent = Agent(name="text-only", instructions="Answer text questions.")
# Agent chat() has no attachments parameter — attachments are skipped automatically

Best Practices

config = BotConfig(max_inbound_media_bytes=2 * 1024 * 1024)

config = BotConfig(max_inbound_media_bytes=0)

WARNING: SSRF guard rejected URL: https://internal-cdn.example.com/...

config = BotConfig(metadata={"media_group_window_ms": 1200})

agent = Agent(llm="gpt-4o")          # OpenAI vision
agent = Agent(llm="claude-3-7-sonnet-20250219")  # Anthropic vision
agent = Agent(llm="gemini/gemini-2.0-flash")      # Google vision

Related