Telegram Integration¶
This guide walks you through setting up and using the Telegram agent in your AgentConnect applications. The Telegram agent allows users to interact with your AI system through the Telegram messaging platform, providing both direct chat interfaces and group chat capabilities.
Prerequisites¶
Before you begin integrating the Telegram agent, ensure you have:
Installed AgentConnect with the required dependencies
A Telegram account
API keys for your preferred LLM provider (Google, OpenAI, Anthropic, or Groq)
Creating a Telegram Bot¶
To use the Telegram integration, you first need to create a bot through Telegram’s BotFather:
Open Telegram and search for
@BotFather
Start a chat with BotFather and use the
/newbot
commandFollow the prompts to create your bot:
Provide a display name for your bot (e.g., “My AgentConnect Assistant”)
Provide a username for your bot (must end with “bot”, e.g., “my_agent_connect_bot”)
BotFather will provide a token that looks like this:
123456789:ABCdefGhIJKlmosdQRsTUVwxyZ
Save this token securely - you’ll need it to initialize your Telegram agent
Warning
Keep your bot token secure! Anyone with this token can control your bot. Never commit it directly in your code. Use environment variables or secure storage.
Basic Telegram Agent Setup¶
The simplest way to set up a Telegram agent is as follows:
import os
import asyncio
from dotenv import load_dotenv
from agentconnect.agents.telegram import TelegramAIAgent
from agentconnect.core.types import AgentIdentity, ModelProvider, ModelName
from agentconnect.core.registry import AgentRegistry
from agentconnect.communication.hub import CommunicationHub
# Load environment variables (assuming you've stored your tokens in a .env file)
load_dotenv()
async def main():
# Create agent registry and communication hub
registry = AgentRegistry()
hub = CommunicationHub(registry)
# Create Telegram agent
agent = TelegramAIAgent(
agent_id="telegram_assistant",
name="My Telegram Assistant",
provider_type=ModelProvider.GOOGLE, # Or your preferred provider
model_name=ModelName.GEMINI2_FLASH, # Or your preferred model
api_key=os.getenv("GOOGLE_API_KEY"), # Your API key
identity=AgentIdentity.create_key_based(),
telegram_token=os.getenv("TELEGRAM_BOT_TOKEN") # Your Telegram token
)
# Register agent with the hub
await hub.register_agent(agent)
# Start the agent
try:
await agent.run()
except KeyboardInterrupt:
print("Shutting down...")
finally:
# Clean shutdown
await agent.stop_telegram_bot()
await hub.unregister_agent(agent.agent_id)
if __name__ == "__main__":
asyncio.run(main())
Save this code in a file (e.g., telegram_bot.py
) and run it. Your bot should now be active on Telegram.
Advanced Configuration¶
The TelegramAIAgent supports various configuration options:
agent = TelegramAIAgent(
agent_id="telegram_assistant",
name="My Telegram Assistant",
provider_type=ModelProvider.GOOGLE,
model_name=ModelName.GEMINI2_FLASH,
api_key=os.getenv("GOOGLE_API_KEY"),
identity=AgentIdentity.create_key_based(),
telegram_token=os.getenv("TELEGRAM_BOT_TOKEN"),
# Additional options
personality="helpful, friendly, and concise",
organization_id="my_organization",
groups_file="groups.txt", # File to store registered group IDs
max_tokens_per_minute=5500, # Rate limiting
max_tokens_per_hour=100000, # Rate limiting
capabilities=[...] # Custom capabilities beyond defaults
)
Interacting with Your Telegram Agent¶
Once your agent is running, you can interact with it in several ways:
Private Chat¶
Open Telegram and search for your bot’s username
Start a chat with your bot
Send the
/start
command to initialize the botSend messages directly to your bot, which will respond using the configured LLM
Group Chat¶
Add your bot to a Telegram group
Send the
/start
command in the group to register itMention your bot (e.g.,
@my_agent_connect_bot what's the weather today?
) to interact with it
The bot will only respond in groups when explicitly mentioned or when a message is directly replied to.
Bot Commands¶
The Telegram agent comes with several built-in commands:
/start
- Initialize the bot or get a welcome message/help
- Display help information about the bot’s capabilities/about
- Show information about the bot and AgentConnect
You can customize these commands or add new ones by modifying the handler methods in your agent.
Media Handling¶
The Telegram agent can process various types of media:
Photos: Send images to the bot for processing or description
Documents: Send files for the bot to analyze (PDF, text, etc.)
Voice Messages: Send voice recordings that the bot can process
Location Data: Share locations with the bot
Here’s an example of how the agent processes media:
User sends a photo to the bot
TelegramAIAgent downloads and processes the image
The agent’s LLM receives context about the image
The agent responds with information about the image content
Integration with Other Agents¶
One of the most powerful features of the TelegramAIAgent is its ability to collaborate with other agents:
# Set up multiple agents
telegram_agent = TelegramAIAgent(...)
research_agent = AIAgent(
agent_id="research_agent",
name="Research Specialist",
provider_type=ModelProvider.ANTHROPIC,
model_name=ModelName.CLAUDE_3_OPUS,
api_key=os.getenv("ANTHROPIC_API_KEY"),
identity=AgentIdentity.create_key_based(),
capabilities=[
Capability(
name="web_research",
description="Can perform detailed web research on any topic",
input_schema={"topic": "string"},
output_schema={"findings": "string", "sources": "list"}
)
]
)
data_visualization_agent = AIAgent(
agent_id="viz_agent",
name="Visualization Expert",
provider_type=ModelProvider.OPENAI,
model_name=ModelName.GPT4_VISION,
api_key=os.getenv("OPENAI_API_KEY"),
identity=AgentIdentity.create_key_based(),
capabilities=[
Capability(
name="data_visualization",
description="Creates charts and visualizations from data",
input_schema={"data": "string", "chart_type": "string"},
output_schema={"image_path": "string", "description": "string"}
)
]
)
# Register all agents
await hub.register_agent(telegram_agent)
await hub.register_agent(research_agent)
await hub.register_agent(data_visualization_agent)
# Start all agents
asyncio.create_task(telegram_agent.run())
asyncio.create_task(research_agent.run())
asyncio.create_task(data_visualization_agent.run())
With this setup, when a user interacts with the Telegram bot, a sophisticated workflow can emerge:
Request Interpretation: The Telegram agent analyzes the user’s request to determine what capabilities are needed
Capability Discovery: The agent uses it’s tools to find other agents with the required capabilities
Collaboration Request: The agent sends requests to the appropriate specialized agents
Result Integration: The agent combines results from multiple sources into a coherent response
Content Distribution: The agent can broadcast the finalized content to multiple groups or users
For example, when a user asks:
User: Research the latest developments in quantum computing, create a visualization
of the major players, and send a summary to the Tech and Science groups.
The workflow might look like this:
Telegram agent receives the request and identifies three required capabilities:
Web research
Data visualization
Group messaging
It discovers and collaborates with the research agent to gather information on quantum computing
It takes the research data and requests a visualization from the visualization agent
It formats all the content into a comprehensive announcement with proper formatting
It broadcasts the announcement to the specified groups
The user can later edit or update the announcement through the private chat
This multi-agent collaboration happens seamlessly behind the scenes, with the Telegram agent serving as both the user interface and the orchestration layer.
Advanced Use Cases¶
Dynamic Group Announcements and Broadcasting¶
One of the most powerful features of the Telegram agent is its ability to dynamically create and broadcast announcements to multiple groups. The TelegramAIAgent can handle this autonomously, without requiring any manual implementation from the developer.
The agent uses its built-in collaboration tools (like search_for_agents
and send_collaboration_request
) to interact with other specialized agents (such as research agents). It then uses its Telegram-specific tools (like create_telegram_announcement
and publish_telegram_announcement
) to format and broadcast content to Telegram groups.
As a developer, your role is to configure the TelegramAIAgent with the right personality
prompt to guide this autonomous behavior, rather than coding the workflow manually. For example, your personality prompt might include instructions like:
When users ask you to research topics and broadcast findings, you should:
1. Use collaboration tools to find and query a specialized research agent
2. Format the results in a visually appealing way with proper Markdown
3. Create and preview announcements before broadcasting
4. Send the finalized content to the appropriate Telegram groups
Here’s a practical example of how a user might interact with this feature:
User: Research the latest trends on MCP and create an announcement for all registered groups.
Make the announcement intense and visually appealing.
Bot: I'll research MCP trends and create an announcement for all groups.
[Agent performs research, possibly collaborating with other agents]
Bot: I've prepared the announcement. Here's a preview:
🔥 **BREAKING: MCP MARKET TRENDS UPDATE** 🔥
Our analysis shows three major developments in the MCP space:
- 📈 20% increase in enterprise adoption this quarter
- 🔄 New framework version releasing next month with enhanced security
- 🌐 Growing integration with cloud infrastructure services
[Chart image showing adoption trends]
Would you like me to send this to all registered groups now?
User: Yes, send it.
Bot: Announcement successfully sent to 5 groups.
The TelegramAIAgent can also handle media files (images, documents, videos) as part of announcements, using its built-in tools to process and distribute this content appropriately.
Editing Messages and Announcements¶
The agent’s autonomous capabilities extend to editing previously sent messages or announcements. Using its internal LLM workflow and specialized Telegram tools, the agent can handle edit requests directly through natural language interaction:
User: Edit the announcement I just sent to change "20% increase" to "25% increase"
Bot: I'll update the announcement. Here's the edited version:
🔥 **BREAKING: MCP MARKET TRENDS UPDATE** 🔥
Our analysis shows three major developments in the MCP space:
- 📈 25% increase in enterprise adoption this quarter
- 🔄 New framework version releasing next month with enhanced security
- 🌐 Growing integration with cloud infrastructure services
[Chart image showing adoption trends]
Should I apply this edit to all groups?
User: Yes
Bot: Announcement successfully updated in 5 groups.
This editing capability is particularly useful for:
Correcting information in announcements
Updating time-sensitive information
Refining messaging based on feedback
Super Agent Capabilities¶
The combination of these features effectively makes the Telegram agent a “super agent” that autonomously:
Acts as an interface between users and specialized agents in your network
Performs complex tasks through multi-agent collaboration
Broadcasts results to multiple channels/groups simultaneously
Manages and updates previously sent content
Handles media and formatted text for visually appealing messaging
For example, a user could request:
User: Analyze last month's sales data, create a visualization, and send a summary to the Sales and
Executive groups with appropriate formatting.
The TelegramAIAgent will:
Parse the request to understand the required capabilities
Use its collaboration tools to find and collaborate with a data analysis agent in the network
Get the analysis results and visualizations
Use its Telegram tools to format the content appropriately for professional presentation
Send specifically tailored announcements to the different groups
Allow the user to edit or refine the messages if needed
All of this happens through the agent’s internal LLM workflow, guided by its personality prompt and using the tools provided during initialization, without any need for manual implementation by the developer.
Group Management¶
The Telegram agent can manage group memberships and permissions. It can add or remove users from groups, and it can control access to certain capabilities within those groups.
Customizing the Telegram Agent¶
Note
A detailed guide on customizing and extending the TelegramAIAgent is coming soon in the Advanced Configuration section. This will include advanced configuration options, custom message handling, and integration patterns.
Extending Message Handlers¶
You can customize how your bot handles messages by creating custom handlers:
from agentconnect.agents.telegram._handlers.base_handler import BaseHandler
class CustomHandler(BaseHandler):
async def handle_custom_message(self, message):
# Custom message handling logic
pass
# Register the custom handler with HandlerRegistry
handler_registry.register_handler("custom", CustomHandler())
Adding Custom Commands¶
To add custom commands to your bot:
Create custom handler methods in your implementation
Register them with the HandlerRegistry
Update the help text to include your new commands
Troubleshooting¶
Common Issues¶
Bot Not Responding: Ensure your TELEGRAM_BOT_TOKEN is correct and the bot is running
API Key Issues: Verify your LLM provider’s API key is valid and has sufficient quota
Rate Limiting: If you hit rate limits, adjust the max_tokens parameters or switch providers
Message Processing Errors: Check your logs for detailed error messages
Best Practices¶
Token Security: Never hardcode tokens or API keys in your source code
Error Handling: Implement proper error handling for both Telegram API operations and LLM requests
Graceful Shutdown: Always implement proper shutdown procedures to clean up resources
Group Management: Be mindful of how your bot behaves in group chats
Privacy Considerations: Inform users about data processing and storage
Scaling: For high-traffic bots, consider implementing additional rate limiting and resource management
Next Steps¶
Now that you’ve set up your Telegram agent, consider:
Adding more specialized agents to collaborate with your Telegram interface
Implementing custom tools to enhance your bot’s capabilities
Creating a web dashboard to monitor your bot’s activity
Exploring conversation memory and context management for improved interactions
For a complete working example, see our Telegram Agent Example.