Telegram AI Agent: The Complete Guide to Autonomous AI on Telegram

Teleton is an open-source Telegram AI Agent that operates as a real user account — not a bot. With 125+ built-in tools, multi-model AI reasoning, persistent memory, native TON blockchain integration, and a plugin SDK, it's the most capable way to automate anything on Telegram.

What Is a Telegram AI Agent?

A Telegram AI Agent is an autonomous software program that operates within Telegram using artificial intelligence to understand and execute tasks. Unlike simple chatbots that follow pre-defined scripts, an AI agent reasons through problems, uses tools, maintains memory across sessions, and takes multi-step actions.

Think of the difference between a calculator (chatbot) and a human accountant (AI agent). The calculator can only do what you explicitly tell it. The accountant understands context, remembers your financial history, uses multiple tools (spreadsheets, tax software, banking portals), and proactively identifies issues.

Teleton is the first open-source Telegram AI Agent that operates as a real user account (not a bot) via the MTProto protocol. This gives it access to the full range of Telegram capabilities that bots cannot reach — reading chat history, managing contacts, forwarding messages, handling groups and channels, and more.

Bot vs. Agent vs. Userbot: Key Differences

Understanding the distinction between these three types of Telegram automation is essential for choosing the right approach:

Telegram Bot (Bot API)

• Uses the Bot API — a simplified HTTP API maintained by Telegram
• Requires a bot token from @BotFather
• Cannot read chat history before the bot was added
• Cannot manage contacts, folders, or user-level settings
• Cannot join groups on its own — must be added by an admin
• Receives messages only when directly addressed (commands or mentions)
• Marked as "bot" in the UI — users know they're talking to a bot

Telegram Userbot (MTProto)

• Uses MTProto — the same protocol used by official Telegram apps
• Operates under a real user account
• Full access to all Telegram features: chat history, contacts, groups, channels, folders, stickers, gifts, stars, and more
• Can read all messages in conversations, not just those directed at it
• Appears as a regular user — no "bot" label
• Requires a Telegram account with phone number and API credentials from my.telegram.org

Telegram AI Agent (Teleton)

• A userbot powered by AI — combines MTProto access with LLM reasoning
• Understands natural language instead of just commands
• Reasons through multi-step problems using an agentic loop with tool calling
• Maintains persistent memory across restarts
• Supports 15 LLM providers and 70+ models (Claude, GPT-4, Gemini, Grok, Groq, OpenRouter, Ollama, DeepSeek, and more)
• Includes 125+ built-in tools and a Plugin SDK for custom extensions
• Integrates natively with the TON blockchain for DeFi, wallets, and NFTs

MTProto Architecture: How It Works

Teleton connects to Telegram through GramJS, a JavaScript implementation of the MTProto protocol. This is the same protocol used by the official Telegram Desktop, Android, and iOS apps.

The architecture works in three layers:

1. Transport Layer (MTProto / GramJS)

GramJS handles the encrypted connection to Telegram's servers, session management, and the raw API calls. Your Telegram session is stored locally and persists across restarts.

2. Tool Layer (125+ Tools)

Teleton exposes Telegram's capabilities as structured tools that the AI can call. Each tool has a defined input schema, output format, and scope (DM-only, group-allowed, or admin-only). Examples:

• Messaging — send messages, reply, forward, edit, delete, pin, translate
• Media — send photos, videos, documents, voice messages, stickers
• Groups — create, manage members, set permissions, configure admin rights
• Channels — post, schedule, manage subscribers, get analytics
• Contacts — add, search, manage, export
• Folders — create, organize chats, filter by criteria
• Search — search messages across chats with filters
• TON — wallet, DeFi trading, DNS, NFTs (see TON AI Agent)
• Web — search the web, fetch and read URLs
• Files — read and manage workspace files

3. Reasoning Layer (Agentic Loop)

The AI model receives the user's message plus context (conversation history, memory, available tools) and decides what actions to take. It can chain multiple tool calls together to complete complex tasks. For example:

User: "Summarize the last 50 messages in @crypto_channel 
       and post a summary in our group chat"

Agent reasoning:
1. Call get_messages(chat: "@crypto_channel", limit: 50)
2. Analyze and summarize the messages
3. Call send_message(chat: "our group chat", text: summary)
4. Report completion to user

125+ Built-in Tools

Teleton ships with over 125 tools organized into categories:

Telegram Tools (53 methods)

Complete access to Telegram's user-level API: sending messages (text, media, formatted), reading chat history, managing contacts, groups, channels, folders, stickers, gifts, stars, and more. Every action a human can perform in Telegram is available as a tool.

TON Blockchain Tools (15+ methods)

Native wallet management, DeFi trading on STON.fi and DeDust, DNS auctions, NFT operations, and balance checking. Learn more in the TON AI Agent guide.

Memory Tools

Save and recall information across sessions. The agent can store facts, user preferences, and context that persists across restarts.

Web Tools

Search the web using Tavily (free tier available) and fetch readable content from any URL. The agent can research topics and bring external information into conversations.

System Tools

Scheduled tasks (cron-like), file management for the workspace directory, and admin commands for runtime configuration.

Tool RAG: Smart Tool Selection

With 125+ tools, sending all of them to the LLM every message would be expensive and slow. Teleton uses Tool RAG — semantic search over tool descriptions to select only the top 25 most relevant tools per message. This reduces token usage significantly and is essential for providers with tool count limits.

Multi-Model AI: 15 LLM Providers, 70+ Models

Teleton supports fifteen LLM providers, each with different strengths:

Switch providers with a single config change (provider: anthropic) or at runtime using the /model admin command. No code changes needed.

Persistent Memory System

Unlike stateless chatbots that forget everything between sessions, Teleton implements a hybrid retrieval memory system:

• Vector search — 384-dimensional local ONNX embeddings for semantic similarity (no external API calls)
• Full-text search — SQLite FTS5 with BM25 ranking for keyword matching
• Reciprocal Rank Fusion — Combines both search methods for optimal recall

The memory system indexes:

• Persistent memory entries (facts, preferences, instructions)
• Daily session logs (summarized conversation history)
• Telegram messages from conversations
• Workspace markdown files

When conversation context approaches the token limit, auto-compaction kicks in: the agent summarizes the conversation using a utility model, archives the full transcript, and continues with fresh context. Observation masking compresses old tool results, saving ~90% of context space.

Plugin SDK & Extensibility

Teleton's Plugin SDK lets you build custom tools as JavaScript (ESM) modules:

// plugins/weather/index.js
export const tools = [{
  name: 'get_weather',
  description: 'Get current weather for a city',
  parameters: {
    type: 'object',
    properties: {
      city: { type: 'string', description: 'City name' }
    },
    required: ['city']
  },
  execute: async ({ city }, sdk) => {
    const data = await fetch(`https://api.weather.com/${city}`);
    return { temperature: data.temp, conditions: data.weather };
  }
}];

The SDK provides namespaced access to:

• sdk.telegram — 53 messaging methods
• sdk.ton — wallet, payments, NFT operations
• sdk.secrets — 3-tier secret resolution (env, file, config)
• sdk.storage — key-value store with TTL support
• sdk.db — isolated SQLite database per plugin
• sdk.log — prefixed logger with dashboard streaming

Enable dev.hot_reload: true for automatic plugin reloading during development. Browse the plugin directory for 34 community plugins with 172+ tools.

Use Cases

Personal Assistant

Set up reminders, schedule messages, summarize long conversations, translate messages in real-time, and manage your Telegram inbox through natural language.

Community Management

Automate group moderation, welcome new members, answer recurring questions using persistent memory, manage admin permissions, and schedule channel posts.

DeFi & Crypto Trading

Execute token swaps on STON.fi and DeDust, monitor prices, manage your TON wallet, and automate trading strategies. See the TON AI Agent guide for details.

Customer Support

Build an AI-powered support agent that remembers customer history, uses knowledge base tools, and escalates complex issues to human agents.

Content Automation

Schedule and post content across multiple channels, aggregate news from sources, generate summaries, and manage editorial calendars.

Development & DevOps

Receive deployment notifications, query monitoring systems, trigger CI/CD pipelines, and manage infrastructure — all from your Telegram.

How to Set Up Your Telegram AI Agent

Step 1: Install Teleton

# Via npm (recommended)
npm install -g teleton@latest

# Via Docker
docker pull ghcr.io/tonresistor/teleton-agent:latest

# From source
git clone https://github.com/TONresistor/teleton-agent.git
cd teleton-agent && npm install && npm run build

Step 2: Get Telegram API Credentials

1. Go to my.telegram.org/apps
2. Log in with your phone number
3. Navigate to "API development tools"
4. Create an application
5. Save your api_id and api_hash (these are permanent)

Step 3: Run the Setup Wizard

teleton setup

The wizard configures:

• LLM provider and API key
• Telegram authentication (phone number, login code, optional 2FA)
• Access policies (who can DM the agent, which groups it can participate in)
• Admin user ID (your Telegram user ID for admin commands)
• TON wallet generation

Step 4: Start the Agent

teleton start

The agent connects to Telegram and begins processing messages. Send it a message from your admin account to test:

"Hello! What can you do?"
"Summarize the last 20 messages in this chat"
"Remind me to check the markets in 2 hours"

Comparison: Teleton vs n8n vs Make vs Relevance AI

Frequently Asked Questions

Get Started with Your Telegram AI Agent

Install Teleton in under 5 minutes and start automating Telegram with AI:

npm install -g teleton@latest
teleton setup
teleton start

Join the Telegram community for support, or explore the source code on GitHub.

Learn more about TON blockchain automation or browse the plugin directory for 34 community plugins with 172+ tools.