> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram

> TelegramTools enables an Agent to send text, photos, documents, video, audio, animations, and stickers to a Telegram chat via the Bot API.

**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

```shell theme={null}
uv pip install -U "agno[telegram]" openai
```

```shell theme={null}
export OPENAI_API_KEY=***
export TELEGRAM_TOKEN=***
export TELEGRAM_CHAT_ID=***
```

## Example

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

```python cookbook/91_tools/telegram_tools.py theme={null}
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

* [Tools](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/tools/telegram.py)
* [Telegram interface docs](https://agno-v2.mintlify.site/agent-os/interfaces/telegram/introduction.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.