Self-host Telegram bots

Note

Self-hosting helpers for Telegram bots in .NET are coming soon.

Note

Self-hosting helpers for Telegram bots are not currently available for Go.

agent-framework-hosting-telegram converts Telegram Bot API updates into Agent Framework run values and renders final or streaming runs as Bot API operations. It does not provide a bot client, polling runtime, webhook router, command registry, or delivery framework.

pip install --pre agent-framework agent-framework-foundry agent-framework-hosting agent-framework-hosting-telegram azure-identity

Use any Telegram client library that can supply an update payload and execute the operations returned by the helpers. The sample uses aiogram, but the helpers are not tied to it.

Process an update

The aiogram webhook sample verifies Telegram's secret header, dispatches the update, and uses a bot-scoped session ID to preserve an agent session for each private chat or shared group chat.

Before dispatching a command, pass the current bot username to telegram_command(update, bot_username=...). The helper returns None for commands addressed to another bot, including commands in message text, callback data, and media captions. Omitting bot_username preserves target-agnostic parsing for compatibility.

For polling and webhook setup, command handling, inbound media policy, streaming edits, and production deployment guidance, see the local Telegram sample.

Important

Verify Telegram webhook deliveries before processing updates. A webhook secret authenticates Telegram's delivery, but it does not authorize the Telegram user or chat to access application data. Treat chat and user IDs as untrusted until your application applies its authorization policy.

Next steps

Go deeper: