Telegram Tools

If you want to add the ability for your agents to send and/or retrieve messages for your Telegram channel/group/bot TelegramSendTool and TelegramRetrieveTool are easy to add.

If you haven’t had a chance to read about how AG2’s Communication Platform agents and tools work, read the overview first.

Installation

Install AG2 with the LLM model provider and Telegram platform extra.

pip install ag2[openai,commsagent-telegram]

Capabilities

TelegramSendTool can:

• Construct and send a message to the configured channel. If a message is longer than the platforms permitted message length, they will split the message into multiple messages.

TelegramRetrieveTool can:

• Retrieve the latest X messages from a channel.
• Retrieve messages since a given date.
• Retrieve messages since a given message ID.
• Retrieve a message given its ID.
• Retrieve messages using a search string (and this can be done in combination with the retrieval options above).

Consider TelegramAgent if you don’t want to build your agent with these tools, it is a ready-to-go AG2 agent that already incorporates the tools and messaging instructions.

Platform configuration

The tools require authentication (API ID and hash) and target Bot/Group/Channel details in order to send/retrieve messages.

The tools are different to the Discord and Slack tools in that you can send/retrieve messages to/from a bot channel, a group channel, a channel, or even your own private channel. This is all handled by giving the respective ID to the chat_id parameter when creating the agent.

Here’s how to establish your API ID and Hash:

• API ID and Hash

If you want to create a bot, which is optional but allows you to send messages to the bot channel:

• In Telegram, search for @BotFather
• Click on @BotFather (make sure it’s the correct one!) and click START
• Message /newbot
• Give it a name then a username
• You’ll then receive a token for your bot and you see the links below to get the ID for your bot

There are four types of chat_ids you can send to:

• Bot chat
• Group chat
• Channel chat
• Private chat (noted in Telegram as Saved Messages)

To find these the IDs for these, here are some references:

• Bot, Private, Channel, Group IDs
• Group and Channel IDs
• Group ID

It takes a bit of time to get this sorted, but once you have your token and IDs, you’re ready to go!

Code example

Let’s add the Telegram Send and Retrieve tools to an agent and have them executed by another agent in as simple 2-agent chat.

# Tools are available in the autogen.tools namespace
from autogen import ConversableAgent, LLMConfig
from autogen.tools.experimental import TelegramRetrieveTool, TelegramSendTool

# For running the code in Jupyter, use nest_asyncio to allow nested event loops
#import nest_asyncio
#nest_asyncio.apply()

llm_config = LLMConfig(model="gpt-4o-mini", api_type="openai")

# Our tool executor agent, which will run the tools once recommended by the telegram_agent, no LLM required
executor_agent = ConversableAgent(
    name="executor_agent",
    human_input_mode="NEVER",
)

with llm_config:
    telegram_agent = ConversableAgent(name="telegram_agent")

# Authentication and target Chat ID (in this case a Group chat)
api_id = "123....."
api_hash = "a2e............................."
_chat_id_group = "-4712345678"

# Create our send tool
telegram_send_tool = TelegramSendTool(api_id=api_id, api_hash=api_hash, chat_id=_chat_id_group)

# Register it for recommendation by our Telegram agent
telegram_send_tool.register_for_llm(telegram_agent)

# Register it for execution by our executor agent
telegram_send_tool.register_for_execution(executor_agent)

# And the same for our our retrieve tool
telegram_retrieve_tool = TelegramRetrieveTool(api_id=api_id, api_hash=api_hash, chat_id=_chat_id_group)
telegram_retrieve_tool.register_for_llm(telegram_agent)
telegram_retrieve_tool.register_for_execution(executor_agent)

# Let’s send a message to our Telegram channel, with a joke for the day.
# We’ll limit it to 2 turns, allowing the Telegram agent to receive the request,
# construct and recommend the send tool, and then the executor agent to execute the tool,
# sending the message to the Telegram group.
executor_agent.initiate_chat(
    recipient=telegram_agent,
    message="Let's send a message to Telegram giving them a joke for the day about AI agentic frameworks",
    max_turns=2,
)

Here’s the message it sent.

If you wanted to retrieve the last 10 messages and get their IDs:

executor_agent.initiate_chat(
    recipient=telegram_agent,
    message="Retrieve the latest 10 messages from Telegram, getting the IDs and a one sentence summary of each.",
    max_turns=2,
)

If you want to get all messages after a given ID, in this case ID 85. This is useful if you want to poll and retrieve new messages since the last one you retrieved.

executor_agent.initiate_chat(
    recipient=telegram_agent,
    message="Retrieve all messages since message ID 85, summarising each.",
    max_turns=2,
)

Tool execution

In AG2 the tool execution is typically handled by a separate agent that will follow the agent in the conversation (unless its in a swarm whereby tools are executed automatically). So, you will need to register the tools with another agent for execution.

You will see an example of this is the example code above.

Edit this page