Telegram - Agno

TelegramTools enable an Agent to send messages and media to Telegram chats using the Telegram Bot API. Thirteen tool methods cover sending media, editing and deleting messages, reactions, pins, chat metadata, and file downloads.

Prerequisites

uv pip install -U "agno[telegram]" openai

export OPENAI_API_KEY=***
export TELEGRAM_TOKEN=***
export TELEGRAM_CHAT_ID=***

Example

The following agent will send a message to a Telegram chat.

cookbook/91_tools/telegram_tools.py

from agno.agent import Agent
from agno.tools.telegram import TelegramTools

# How to get the token and chat_id:
# 1. Create a new bot with BotFather on Telegram. https://core.telegram.org/bots/features#creating-a-new-bot
# 2. Get the token from BotFather.
# 3. Send a message to the bot.
# 4. Get the chat_id by going to the URL:
#    https://api.telegram.org/bot<your-bot-token>/getUpdates

agent = Agent(
    name="telegram",
    tools=[TelegramTools()],
)

agent.print_response("Send message to telegram chat a paragraph about the moon")

Toolkit Params

Parameter	Type	Default	Description
`chat_id`	`Optional[str]`	`None`	Default chat ID. Falls back to `TELEGRAM_CHAT_ID` env var.
`token`	`Optional[str]`	`None`	Bot token. Falls back to `TELEGRAM_TOKEN` env var.
`output_directory`	`Optional[str]`	`None`	Directory for files downloaded by `get_file`. Setting it also enables saving downloads.
`save_downloads`	`bool`	`False`	Save downloaded files locally. Otherwise, `get_file` returns base64 content.
`enable_send_message`	`bool`	`True`	Enable `send_message` tool.
`enable_send_photo`	`bool`	`False`	Enable `send_photo` tool.
`enable_send_document`	`bool`	`False`	Enable `send_document` tool.
`enable_send_video`	`bool`	`False`	Enable `send_video` tool.
`enable_send_audio`	`bool`	`False`	Enable `send_audio` tool.
`enable_send_animation`	`bool`	`False`	Enable `send_animation` tool (GIFs).
`enable_send_sticker`	`bool`	`False`	Enable `send_sticker` tool.
`enable_edit_message`	`bool`	`False`	Enable `edit_message` tool.
`enable_delete_message`	`bool`	`False`	Enable `delete_message` tool.
`enable_react_with_emoji`	`bool`	`False`	Enable `react_with_emoji` tool.
`enable_pin_message`	`bool`	`False`	Enable `pin_message` tool.
`enable_get_chat`	`bool`	`False`	Enable `get_chat` tool.
`enable_get_file`	`bool`	`False`	Enable `get_file` tool.
`all`	`bool`	`False`	Enable all tools. Overrides individual flags.

Toolkit Functions

Function	Description
`send_message`	Send a text message to a chat.
`send_photo`	Send a photo (bytes) with optional caption.
`send_document`	Send a document (bytes) with filename and optional caption.
`send_video`	Send a video (bytes) with optional caption.
`send_audio`	Send an audio file (bytes) with optional caption and title.
`send_animation`	Send an animation/GIF (bytes) with optional caption.
`send_sticker`	Send a sticker (bytes).
`edit_message`	Edit a previously sent message by `message_id`.
`delete_message`	Delete a message by `message_id`.
`react_with_emoji`	Add an emoji reaction to a message.
`pin_message`	Pin a message with optional notification suppression.
`get_chat`	Return metadata for the configured chat.
`get_file`	Download a Telegram file and return a local path or base64 content.

Each method returns a JSON string with a status field. Success fields vary by operation. Errors include a message field.

Developer Resources