Outbound Media Delivery

Agents can now return images, charts, and files that are automatically delivered through the bot adapter’s native upload primitive — Telegram send_photo, Slack files_upload_v2, Discord file send, and more.

from praisonaiagents import Agent

chart_agent = Agent(
    name="ChartAgent",
    instructions="Generate charts and return file paths in the media field.",
)
chart_agent.start("Draw a sales chart for Q1 and send it to the user.")

The user messages the bot; generated images and files upload through the channel adapter automatically.

Outbound media now honours threaded targets: when the delivery route names a thread — Slack thread_ts, Telegram forum topic, or Discord thread — the attachment lands in the same thread as the text reply. Adapters that don’t support threads are completely unaffected.

Outbound media uploads share the same retry/backoff path as text replies — DeliveryRouter.send_media wraps the upload in deliver_with_retry, reusing the adapter’s configured BackoffPolicy (or a sensible default). See Retry & backoff on transient failures below and Outbound Resilience for the underlying policy config.

Quick Start

Simple Usage

from praisonaiagents import Agent

chart_agent = Agent(
    name="ChartAgent",
    instructions="""
    Generate the requested chart, save it under /tmp/agent-media/,
    then return a message that includes the file path in the 'media' field.
    """,
)

With Configuration

roles:
  - role: ChartAgent
    backstory: Generates and delivers charts.
    tasks:
      - description: Draw a chart for the user's request.

media_delivery:
  enabled: true
  max_size_mb: 10
  strict: true
  allowlist_roots:
    - /tmp/agent-media
  recent_mtime_seconds: 300

Start the bot:

praisonai bot telegram --config bot.yaml

Users receive text plus the chart image attached automatically.

How It Works

When an agent returns a media file path, the gateway’s outbound binding validates it through the path safety guard and delivers it via the adapter’s native primitive:

Path safety guard

validate_media_delivery_path() runs two checks before any file is sent: System directory denylist (always blocked): /etc, /proc, /sys, ~/.ssh, ~/.aws, ~/.gnupg, gateway secret/pairing directories. Credential basename denylist (always blocked): .env, id_rsa, id_ecdsa, id_ed25519, .npmrc, .netrc, and similar credential filenames — matched from any directory.

Configuration (`media_delivery` YAML block)

media_delivery:
  enabled: true
  max_size_mb: 25
  strict: false
  allowlist_roots:
    - /var/agent/output
    - /tmp/agent-media
  recent_mtime_seconds: 600
  basename_denylist:
    - secret_config.yml

`OutboundMediaPolicy` fields

Field	Type	Default	Description
`enabled`	`bool`	`True`	Master switch. Quoted `"false"` in YAML also disables
`max_size_mb`	`int`	`25`	Per-file size cap in megabytes
`strict`	`bool`	`False`	If `True`, only deliver files inside `allowlist_roots` or with `mtime` within `recent_mtime_seconds`
`allowlist_roots`	`list[str]`	`[]`	Strict-mode: only files under these roots are delivered
`recent_mtime_seconds`	`int`	`600`	Strict-mode: only files modified within this window (seconds) are delivered
`basename_denylist`	`list[str]`	`[]`	Extra basenames added on top of the built-in denylist

Platform Support

Platform	Native primitive	Media types
Telegram	`send_photo`, `send_document`	Images, documents
Slack	`files_upload_v2`	Any file type
Discord	File attachment	Any file type

PlatformCapabilities.supports_media is checked per adapter — platforms that don’t support file uploads receive text-only replies and the attachment is skipped with a log entry.

Threaded media delivery

Attachments follow the same platform:channel_id:thread_id grammar the text path uses. When a route names a thread, both the text reply and any uploaded file land in that thread.

from praisonai.bots import DeliveryRouter

# Scheduled attachment into a Slack thread
router.send_media("slack:C0123456:1728987654.001234", "/tmp/report.pdf",
                  caption="Weekly report")
# → Slack files_upload_v2(..., thread_ts="1728987654.001234")

# Telegram forum topic
router.send_media("telegram:-1001234567890:42", "/tmp/chart.png",
                  caption="Q1 chart")
# → bot.send_photo(..., message_thread_id=42)

Platform	`thread_id` becomes	Ignored on non-threaded adapters
Slack	`thread_ts` on `files_upload_v2`	✅
Telegram	`message_thread_id` on `send_photo` / `send_document`	✅
Discord	Thread channel id used as the send target	✅
WhatsApp / Email / custom	— (no thread concept)	✅ silently dropped

DeliveryRouter.send_media resolves the thread from the target and forwards it to deliver_media_to_adapter, which passes it through each transport’s native keyword only when the primitive accepts it — so non-threaded adapters never raise.

Retry & backoff on transient failures

Media uploads go through the same deliver_with_retry wrapper as text replies. A transient transport failure — HTTP 5xx, rate limit, connection reset — is retried with bounded exponential backoff (honouring a server-mandated Retry-After hint) instead of silently dropping the attachment on the first blip.

Which backoff policy is used?

DeliveryRouter.send_media reuses the adapter’s already-configured _outbound_backoff BackoffPolicy if one is set (matching the text path). If the adapter exposes no policy, a sensible default is used:

Field	Default
`initial_ms`	`1000`
`max_ms`	`10000`
`factor`	`1.5`
`max_attempts`	`3`

To customise, set outbound_resilience on the channel in praisonai.yml (the same block that tunes text retries — see Outbound Resilience). The media upload picks up the same values automatically.

Non-retryable outcomes are preserved

Outcome	Behaviour
Adapter exposes no upload primitive	Returns `False` immediately — no retry.
Missing optional `discord` package	Logged as “unavailable”, returns `False` — no retry.
Permanent transport error (e.g. 4xx that is not 429)	Surfaces as a failed send after policy exhaustion.

Prior to this fix the Discord native upload branch caught every exception locally and returned False, which bypassed the retry wrapper entirely — a transient blip on Discord silently dropped the file. That branch now only catches the missing optional discord dependency; every other transport error propagates so deliver_with_retry can apply the same backoff Slack and Telegram already got.

Common Patterns

Chart generation bot

from praisonaiagents import Agent
import matplotlib.pyplot as plt
import os

chart_agent = Agent(
    name="ChartAgent",
    instructions="""
    When asked for a chart:
    1. Generate it using matplotlib
    2. Save to /tmp/agent-media/<filename>.png
    3. Return the file path in your response
    """,
)

media_delivery:
  enabled: true
  max_size_mb: 10
  strict: true
  allowlist_roots:
    - /tmp/agent-media
  recent_mtime_seconds: 300

Multi-tenant / hosted gateway (strict mode)

For hosted environments where multiple users share the same gateway, enable strict mode with an explicit output directory:

media_delivery:
  enabled: true
  max_size_mb: 5
  strict: true
  allowlist_roots:
    - /var/agent/output
  recent_mtime_seconds: 120
  basename_denylist:
    - config.yml
    - secrets.json

Disable media delivery

media_delivery:
  enabled: false

Or with quoted string (both are equivalent):

media_delivery:
  enabled: "false"

Summary Messages

When media delivery completes, BotOutboundMessenger.send appends a summary:

2 attachment(s) delivered, 1 skipped

Skipped files (denied by path guard, over size cap, etc.) are logged at debug level and never cause the message send to fail.

Best Practices

Write agent output to a dedicated directory

Configure your agent to save all generated files to a single directory like /tmp/agent-media/ and set that as the allowlist_roots entry. This keeps the path guard simple and predictable.

Enable strict mode for production

In production or multi-tenant gateways, set strict: true with explicit allowlist_roots. This prevents agents from accidentally delivering files from unexpected locations.

Set a reasonable size cap

Default is 25 MB. Telegram and Slack have their own size limits — set max_size_mb below those limits to fail fast at the gateway rather than at the adapter.

Never save credentials near the output directory

The basename denylist blocks common credential filenames, but keep your output directory completely separate from config directories. Symlink attacks are also blocked (symlinks are resolved before path checks).

Target the thread for reports that belong to a conversation

Use platform:channel_id:thread_id — not just platform:channel_id — for reports and charts that belong to an ongoing thread. Text and attachment now land together in the same thread; the :channel_id form still posts to the parent chat.

Messaging Bots

Full bot setup and configuration guide

Channels Gateway

Gateway channel routing and configuration

Gateway

Gateway architecture and YAML reference

Bot Inbound Media

Handle images and files sent by users

Voice Notes

Linear Bot

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Outbound Media Delivery

Quick Start

How It Works

Path safety guard

Configuration (`media_delivery` YAML block)

`OutboundMediaPolicy` fields

Platform Support

Threaded media delivery

Retry & backoff on transient failures

Which backoff policy is used?

Non-retryable outcomes are preserved

Common Patterns

Chart generation bot

Multi-tenant / hosted gateway (strict mode)

Disable media delivery

Summary Messages

Best Practices

Messaging Bots

Channels Gateway

Gateway

Bot Inbound Media

​Quick Start

​How It Works

​Path safety guard

​Configuration (media_delivery YAML block)

​OutboundMediaPolicy fields

​Platform Support

​Threaded media delivery

​Retry & backoff on transient failures

​Which backoff policy is used?

​Non-retryable outcomes are preserved

​Common Patterns

​Chart generation bot

​Multi-tenant / hosted gateway (strict mode)

​Disable media delivery

​Summary Messages

​Best Practices

​Related

Messaging Bots

Channels Gateway

Gateway

Bot Inbound Media

Quick Start

How It Works

Path safety guard

Configuration (`media_delivery` YAML block)

`OutboundMediaPolicy` fields

Platform Support

Threaded media delivery

Retry & backoff on transient failures

Which backoff policy is used?

Non-retryable outcomes are preserved

Common Patterns

Chart generation bot

Multi-tenant / hosted gateway (strict mode)

Disable media delivery

Summary Messages

Best Practices

Related