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

# Telegram

> Deploy agents to Telegram for direct and group chat interactions.

The Telegram interface turns any Agno agent, team, or workflow into a Telegram bot with streaming responses, media handling, and group chat support.

## Quick Start

```python telegram_agent.py theme={null}
from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.os.app import AgentOS
from agno.os.interfaces.telegram import Telegram

agent = Agent(name="Assistant", model=OpenAIResponses(id="gpt-5.4"))

agent_os = AgentOS(
    agents=[agent],
    interfaces=[Telegram(agent=agent)],
)
app = agent_os.get_app()
```

```bash theme={null}
uv pip install 'agno[telegram]'
python -m agno.os.serve telegram_agent:app --port 7777
```

## How It Works

| Concept       | Behavior                                                                                          |
| ------------- | ------------------------------------------------------------------------------------------------- |
| **Sessions**  | Each chat is a session (`tg:{agent}:{chat_id}`). Send `/new` to reset.                            |
| **Streaming** | Token-by-token with live message edits, throttled for rate limits                                 |
| **Groups**    | Responds to @mentions and replies by default. Disable privacy mode in BotFather for all messages. |
| **Media**     | Photos, voice, video, documents, stickers in and out                                              |

## Setup

Requires a bot token from [@BotFather](https://t.me/BotFather) and a webhook URL. See the [setup guide](/agent-os/interfaces/telegram/setup) for step-by-step instructions.

**Environment variables:**

```bash theme={null}
export TELEGRAM_TOKEN="..."
export TELEGRAM_WEBHOOK_SECRET_TOKEN="..."  # production only
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Full Guide" icon="book" href="/agent-os/interfaces/telegram/introduction">
    Sessions, groups, media, commands, and troubleshooting.
  </Card>

  <Card title="Reference" icon="square-sliders" href="/agent-os/interfaces/telegram/reference">
    All parameters, endpoints, and events.
  </Card>

  <Card title="Examples" icon="code" href="/agent-os/usage/interfaces/telegram/basic">
    Agents, teams, workflows, and multimodal examples.
  </Card>

  <Card title="TelegramTools" icon="wrench" href="/tools/toolkits/social/telegram">
    Proactive messaging, photos, and message management.
  </Card>
</CardGroup>