diff --git a/agent-os/interfaces/overview.mdx b/agent-os/interfaces/overview.mdx index b457881e..08672dac 100644 --- a/agent-os/interfaces/overview.mdx +++ b/agent-os/interfaces/overview.mdx @@ -24,6 +24,13 @@ Interfaces enable exposing Agno agents, teams, and workflows through various com > Deploy agents as Slack applications for team collaboration + + Deploy agents as Telegram bots with streaming and full media support + +Install the Telegram SDK: `pip install 'agno[telegram]'` + + + +In DMs, each chat gets its own session ID (`tg:{chat_id}`). In groups, sessions are scoped by reply thread (`tg:{chat_id}:thread:{message_id}`), so each conversation thread maintains its own context. + + +## Example Usage + +Create an agent, expose it with the `Telegram` interface, and serve via `AgentOS`: + +```python basic.py +from agno.agent import Agent +from agno.models.openai import OpenAIChat +from agno.os import AgentOS +from agno.os.interfaces.telegram import Telegram + +telegram_agent = Agent( + name="Telegram Bot", + model=OpenAIChat(id="gpt-4o-mini"), + add_history_to_context=True, + num_history_runs=3, + add_datetime_to_context=True, + markdown=True, +) + +agent_os = AgentOS( + agents=[telegram_agent], + interfaces=[Telegram(agent=telegram_agent)], +) +app = agent_os.get_app() + +if __name__ == "__main__": + agent_os.serve(app="basic:app", port=7777, reload=True) +``` + +### Streaming + +Enable streaming to progressively update a Telegram message as tokens arrive, similar to how ChatGPT's Telegram bot works: + +```python streaming.py +agent_os = AgentOS( + agents=[telegram_agent], + interfaces=[ + Telegram( + agent=telegram_agent, + stream=True, + ) + ], +) +``` + +When `stream=True`, the bot sends an initial message and edits it every ~1 second as new content arrives. This is supported for `Agent` only; `Team` and `Workflow` fall back to non-streaming. + +### Team + +```python team.py +from agno.team import Team + +telegram_team = Team( + name="Research Team", + model=OpenAIChat(id="gpt-4o-mini"), + members=[researcher, writer], + markdown=True, +) + +agent_os = AgentOS( + teams=[telegram_team], + interfaces=[Telegram(team=telegram_team)], +) +``` + +### Workflow + +```python workflow.py +from agno.workflow.workflow import Workflow +from agno.workflow.step import Step +from agno.workflow.steps import Steps + +telegram_workflow = Workflow( + name="Draft-Edit Workflow", + steps=[Steps(name="pipeline", steps=[draft_step, edit_step])], +) + +agent_os = AgentOS( + workflows=[telegram_workflow], + interfaces=[Telegram(workflow=telegram_workflow)], +) +``` + +## Core Components + +- `Telegram` (interface): Wraps an Agno `Agent`, `Team`, or `Workflow` for Telegram integration via FastAPI. +- `AgentOS.serve`: Serves the FastAPI app using Uvicorn. + +## `Telegram` Interface + +Main entry point for Agno Telegram applications. + +### Initialization Parameters + +| Parameter | Type | Default | Description | +| ------------------------ | -------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------- | +| `agent` | `Optional[Agent]` | `None` | Agno `Agent` instance. | +| `team` | `Optional[Team]` | `None` | Agno `Team` instance. | +| `workflow` | `Optional[Workflow]` | `None` | Agno `Workflow` instance. | +| `prefix` | `str` | `"/telegram"` | Custom FastAPI route prefix for the Telegram interface. | +| `tags` | `Optional[List[str]]` | `None` | FastAPI route tags for API documentation. Defaults to `["Telegram"]` if not provided. | +| `reply_to_mentions_only` | `bool` | `True` | When `True`, bot responds only to @mentions and replies in groups. All DMs are always processed. | +| `reply_to_bot_messages` | `bool` | `True` | When `True`, bot also responds when a user replies to one of the bot's messages in a group. | +| `stream` | `bool` | `False` | When `True`, progressively edits the Telegram message as content streams in. Agent only. | +| `start_message` | `str` | `"Hello!..."` | Custom response for the `/start` command. | +| `help_message` | `str` | `"Send me..."` | Custom response for the `/help` command. | +| `error_message` | `str` | `"Sorry..."` | Custom message sent when an error occurs during processing. | + +Provide `agent`, `team`, or `workflow`. + +### Key Method + +| Method | Parameters | Return Type | Description | +| ------------ | ---------- | ----------- | -------------------------------------------------- | +| `get_router` | None | `APIRouter` | Returns the FastAPI router and attaches endpoints. | + +## Supported Media + +The Telegram interface handles inbound and outbound media: + +**Inbound** (user sends to bot): +- Text messages +- Photos (with optional caption) +- Stickers +- Voice messages and audio files +- Videos, video notes, and animations +- Documents (any file type) + +**Outbound** (bot sends to user): +- Text (auto-chunked at 4096 characters) +- Images (URL, bytes, or base64) +- Audio files +- Videos +- Documents/files + +## Endpoints + +Mounted under the `/telegram` prefix: + +### `GET /telegram/status` + +- Health/status check for the interface. + +### `POST /telegram/webhook` + +- Receives Telegram webhook updates. +- Validates webhook secret token via `X-Telegram-Bot-Api-Secret-Token` header; bypassed when `APP_ENV=development`. +- Processes text, photo, sticker, voice, audio, video, and document messages. +- Sends replies back to the originating chat (splits messages over 4096 characters). +- In groups, replies are threaded to the original message. +- Responses: `200 {"status": "processing"}` or `{"status": "ignored"}`, `403` invalid token, `500` errors. + +## Testing the Integration + +1. Create a bot via [@BotFather](https://t.me/BotFather) and get the token +2. Set `TELEGRAM_TOKEN` and `APP_ENV=development` +3. Run the app: `python basic.py` +4. Start ngrok: `ngrok http 7777` +5. Set the webhook: `curl "https://api.telegram.org/bot/setWebhook?url=https:///telegram/webhook"` +6. Message the bot on Telegram + +## Troubleshooting + +- Verify `TELEGRAM_TOKEN` is set correctly +- Check that `APP_ENV=development` is set for local testing (bypasses webhook secret validation) +- Confirm the ngrok URL is correct and the webhook is set (`/getWebhookInfo`) +- For groups, ensure the bot has been added to the group and is @mentioned +- Review application logs for download failures or API errors diff --git a/deploy/interfaces.mdx b/deploy/interfaces.mdx index 87296d11..fa6c4627 100644 --- a/deploy/interfaces.mdx +++ b/deploy/interfaces.mdx @@ -18,7 +18,7 @@ Interfaces connect your apps to the platforms and protocols your users already u Connect agents to WhatsApp Business for customer interactions. - Run agents as Telegram bots. + Deploy agents as Telegram bots with streaming and full media support. diff --git a/deploy/interfaces/telegram/overview.mdx b/deploy/interfaces/telegram/overview.mdx index 611afe54..76e4d7ff 100644 --- a/deploy/interfaces/telegram/overview.mdx +++ b/deploy/interfaces/telegram/overview.mdx @@ -1,7 +1,44 @@ --- title: "Overview" +description: "Deploy Agno agents as Telegram bots." --- - - This page is coming soon. If you have any questions or need help, see [getting help](/get-help). - +The Telegram interface lets you serve Agno agents, teams, and workflows as Telegram bots. It handles inbound messages (text, photos, voice, video, documents, stickers), processes them through your agent, and sends responses back to the chat. + +## Key Features + +- **Full media support** - Handles 8 inbound message types and sends images, audio, video, and files back +- **Streaming responses** - Progressively updates messages as content is generated (Agent only) +- **Group chat support** - Responds to @mentions and replies, with per-thread session tracking +- **Works with Agent, Team, and Workflow** - Any Agno entity can power a Telegram bot + +## Quick Start + +```python +from agno.agent import Agent +from agno.models.openai import OpenAIChat +from agno.os import AgentOS +from agno.os.interfaces.telegram import Telegram + +agent = Agent(name="Bot", model=OpenAIChat(id="gpt-4o-mini")) + +agent_os = AgentOS( + agents=[agent], + interfaces=[Telegram(agent=agent, stream=True)], +) +app = agent_os.get_app() +``` + +## Required Configuration + +| Variable | Description | +| -------- | ----------- | +| `TELEGRAM_TOKEN` | Bot token from [@BotFather](https://t.me/BotFather) | +| `APP_ENV` | Set to `development` to bypass webhook validation locally | +| `TELEGRAM_WEBHOOK_SECRET` | (Production) Secret for webhook request validation | + +## Resources + +- [Setup Guide](/production/interfaces/telegram) - Step-by-step bot creation and webhook setup +- [Technical Reference](/agent-os/interfaces/telegram/introduction) - Parameters, endpoints, and media handling +- [Cookbook Examples](https://github.com/agno-agi/agno/tree/main/cookbook/05_agent_os/interfaces/telegram) - Ready-to-run examples diff --git a/docs.json b/docs.json index 63a6aa13..a96e4fe9 100644 --- a/docs.json +++ b/docs.json @@ -2870,6 +2870,7 @@ "group": "Interfaces", "pages": [ "agent-os/interfaces/overview", + "agent-os/interfaces/telegram/introduction", "agent-os/interfaces/whatsapp/introduction", "agent-os/interfaces/a2a/introduction", "agent-os/interfaces/ag-ui/introduction", diff --git a/production/interfaces/overview.mdx b/production/interfaces/overview.mdx index e9a1dd53..a525335f 100644 --- a/production/interfaces/overview.mdx +++ b/production/interfaces/overview.mdx @@ -14,6 +14,9 @@ Expose your agents where your users are. Interfaces connect AgentOS to a platfor Deploy agents as Slack apps that respond to messages and commands. + + Deploy agents as Telegram bots with streaming responses and media support. + Run agents as Discord bots for support, moderation, or custom commands. diff --git a/production/interfaces/telegram.mdx b/production/interfaces/telegram.mdx new file mode 100644 index 00000000..f1fd9fb1 --- /dev/null +++ b/production/interfaces/telegram.mdx @@ -0,0 +1,129 @@ +--- +title: "Telegram Bot" +description: "Build a Telegram bot that responds to messages, handles media, and supports streaming responses using agents." +--- + +Agno and AgentOS make it easy to deploy your agents on Telegram with just 2 extra lines of code. + +This example creates a simple agent for answering questions: + +```python +from agno.agent import Agent +from agno.models.openai import OpenAIChat +from agno.os import AgentOS +from agno.os.interfaces.telegram import Telegram + +telegram_agent = Agent( + name="Telegram Bot", + model=OpenAIChat(id="gpt-4o-mini"), + add_history_to_context=True, + num_history_runs=3, + add_datetime_to_context=True, + markdown=True, +) + +agent_os = AgentOS( + agents=[telegram_agent], + interfaces=[Telegram(agent=telegram_agent)], +) +app = agent_os.get_app() + +if __name__ == "__main__": + agent_os.serve(app="telegram_bot:app", port=7777, reload=True) +``` + + +Install the Telegram dependency: `pip install 'agno[telegram]'` + + + +In DMs, each chat gets its own session. In group chats, sessions are scoped by reply thread so each conversation maintains its own context. + + +## Setup and Configuration + + + + +Ensure you have the following: +- A Telegram account +- ngrok (for development) +- Python 3.7+ + + + +1. Open Telegram and search for [@BotFather](https://t.me/BotFather) +2. Send `/newbot` +3. Follow the prompts to choose a name and username for your bot +4. BotFather will respond with your bot token (looks like `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`) +5. Save this token securely + + + +Create a `.env` file in your project root: +```bash +TELEGRAM_TOKEN="your-bot-token-from-botfather" +``` + +For development, also set: +```bash +APP_ENV="development" +``` +This bypasses webhook secret validation for local testing. + + + +1. Run ngrok to expose your local server: + ```bash + ngrok http 7777 + ``` +2. Copy the `https://` URL provided by ngrok +3. Set the webhook by running: + ```bash + curl "https://api.telegram.org/bot/setWebhook?url=https:///telegram/webhook" + ``` +4. Verify the webhook is set: + ```bash + curl "https://api.telegram.org/bot/getWebhookInfo" + ``` + + + +For production deployments, set a webhook secret for request validation: +```bash +TELEGRAM_WEBHOOK_SECRET="your-random-secret-string" +APP_ENV="production" +``` + +Set the webhook with the secret token: +```bash +curl "https://api.telegram.org/bot/setWebhook?url=https:///telegram/webhook&secret_token=" +``` + + + +Use BotFather to customize your bot: +- `/setdescription` - Set the bot's description +- `/setabouttext` - Set the "About" text +- `/setuserpic` - Set the bot's profile picture +- `/setcommands` - Set the command menu (e.g., `/start`, `/help`) + +To allow the bot to read all messages in groups (not just @mentions): +1. Send `/mybots` to BotFather +2. Select your bot +3. Go to "Bot Settings" > "Group Privacy" +4. Disable privacy mode + + + + + +ngrok is used only for local development and testing. For production deployments, see the [deployment tutorials](/production/templates/overview). + + +## Developer Resources + +- [Telegram Interface](/agent-os/interfaces/telegram/introduction) +- [Deployment Templates](/production/templates/overview) +- [Agent reference](/reference/agents/agent) +- [Discord](https://agno.link/discord)