Feat(Tools): Add Telegram Toolkit with Send/Receive capabilities #1196 #1480

shanthanu47 · 2026-01-05T00:19:51Z

Description

Implemented a new Telegram Toolkit to enable SuperAGI agents to interact with Telegram Bots.
Resolves #1196.

Changes

Added TelegramToolkit class.
Added TelegramSendMessageTool: Sends text messages to a chat ID.
Added TelegramReceiveMessageTool: Fetches recent messages from the bot's history (using getUpdates).
- Enhancement: Returns structure [chat_id] username: message so agents can identify who to reply to.
Integrated standard configuration (TELEGRAM_BOT_TOKEN).

Type of change

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Docs update

Checklist

My pull request is atomic and focuses on a single change.
I have read the contributing guide and my code conforms to the guidelines.
I have documented my changes clearly and comprehensively.
I have added the required tests.

Copilot

Pull request overview

This PR adds a new Telegram Toolkit to enable SuperAGI agents to interact with Telegram bots. However, the implementation has critical issues that prevent the receive functionality from working as described.

Key Changes:

Added TelegramToolkit class with configuration for TELEGRAM_BOT_TOKEN
Added TelegramSendMessageTool to send text messages to Telegram chats
Added TelegramReceiveMessageTool to fetch recent messages (though not integrated into the toolkit)

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 13 comments.

File	Description
`superagi/tools/telegram/telegram_toolkit.py`	Defines the Telegram toolkit but is missing the receive tool in imports and tool list
`superagi/tools/telegram/telegram_send_message.py`	Implements message sending functionality with incomplete response validation
`superagi/tools/telegram/telegram_receive_message.py`	Implements message retrieval with incorrect API parameter usage and incomplete validation
`superagi/tools/telegram/__init__.py`	Exports toolkit and send tool but missing the receive tool export

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-05T00:23:25Z

superagi/tools/telegram/telegram_toolkit.py

+class TelegramToolkit(BaseToolkit, ABC):
+    name: str = "Telegram Toolkit"
+    description: str = "Toolkit containing tools for Telegram integration"
+
+    def get_tools(self) -> List[BaseTool]:
+        return [
+            TelegramSendMessageTool(),
+        ]
+
+    def get_env_keys(self) -> List[ToolConfiguration]:
+        return [
+            ToolConfiguration(key="TELEGRAM_BOT_TOKEN", key_type=ToolConfigKeyType.STRING, is_required=True, is_secret=True)
+        ]


Tests are missing for the TelegramToolkit and its tools. The repository has comprehensive test coverage for other toolkits (e.g., in tests/unit_tests/tools/), and the PR description claims tests have been added. Tests should be included to verify the functionality of TelegramSendMessageTool, TelegramReceiveMessageTool, and the TelegramToolkit class.

Copilot · 2026-01-05T00:23:25Z

superagi/tools/telegram/telegram_send_message.py

+            message : The message to be sent.
+
+        Returns:
+            success message if message is sent successfully or failure message if message sending fails.


The documentation for the _execute method states it returns "success message if message is sent successfully or failure message if message sending fails" but doesn't specify that it can also return error strings for configuration issues or exceptions. The documentation should accurately reflect all possible return types and scenarios.

Suggested change

success message if message is sent successfully or failure message if message sending fails.

str: A human-readable message indicating the result of the operation. This may be:

- A success message if the message is sent successfully.

- A failure message if the Telegram API returns a non-200 status code.

- A configuration error message if the TELEGRAM_BOT_TOKEN is not set.

- An error message describing any exception raised while sending the message.

Copilot · 2026-01-05T00:23:25Z

superagi/tools/telegram/telegram_receive_message.py

+           limit: Number of messages to retrieve.
+
+        Returns:
+            Recent messages or failure message.


The documentation for the _execute method states it returns "Recent messages or failure message" but doesn't specify the exact format of the returned messages or that it can return error strings for configuration issues or exceptions. The documentation should clearly describe the return format: each message as "[chat_id] username: text" separated by newlines, or specific error messages.

Suggested change

limit: Number of messages to retrieve.

Returns:

Recent messages or failure message.

limit: Number of messages to retrieve.

Returns:

str: On success, a single string containing recent text messages, one per line,

where each line is formatted as "[chat_id] username: text" and lines are

separated by newline characters. On failure, a human-readable error message

string such as:

- "Error: TELEGRAM_BOT_TOKEN is not set in the configuration."

- "Error from Telegram: <description>"

- "Failed to retrieve messages. Status Code: <code>. Response: <response body>"

- "Error retrieving messages: <exception message>"

Copilot · 2026-01-05T00:23:26Z

superagi/tools/telegram/telegram_receive_message.py

+            else:
+                return f"Failed to retrieve messages. Status Code: {response.status_code}. Response: {response.text}"
+        except Exception as e:
+            return f"Error retrieving messages: {e}"


The error message "Error retrieving messages: {e}" is too generic and doesn't provide enough context for debugging. It should specify what operation failed, for example: "Failed to retrieve Telegram messages due to network or API error: {e}"

Suggested change

return f"Error retrieving messages: {e}"

return f"Failed to retrieve Telegram messages due to network or API error: {e}"

Copilot · 2026-01-05T00:23:26Z

superagi/tools/telegram/telegram_toolkit.py

+from abc import ABC
+from typing import List
+from superagi.tools.base_tool import BaseTool, BaseToolkit, ToolConfiguration
+from superagi.tools.telegram.telegram_send_message import TelegramSendMessageTool


The TelegramReceiveMessageTool is missing from imports. According to the PR description, this toolkit should include both send and receive capabilities, but the receive tool is not imported here.

Copilot · 2026-01-05T00:23:27Z

superagi/tools/telegram/telegram_send_message.py

+            else:
+                return f"Message sending failed. Status Code: {response.status_code}. Response: {response.text}"
+        except Exception as e:
+            return f"Error sending message: {e}"


The error message "Error sending message: {e}" is too generic and doesn't provide enough context for debugging. It should specify what operation failed, for example: "Failed to send Telegram message due to network or API error: {e}"

Suggested change

return f"Error sending message: {e}"

return f"Failed to send Telegram message to chat_id {chat_id} due to network or API error: {e}"

Copilot · 2026-01-05T00:23:27Z

superagi/tools/telegram/telegram_toolkit.py

+    def get_tools(self) -> List[BaseTool]:
+        return [
+            TelegramSendMessageTool(),
+        ]


The TelegramReceiveMessageTool is not included in the list of tools returned by get_tools(). The PR description states that both send and receive capabilities should be available, but only TelegramSendMessageTool is being returned here. This means agents won't be able to read messages.

Copilot · 2026-01-05T00:23:27Z

superagi/tools/telegram/__init__.py

@@ -0,0 +1,2 @@
+from superagi.tools.telegram.telegram_toolkit import TelegramToolkit
+from superagi.tools.telegram.telegram_send_message import TelegramSendMessageTool


The TelegramReceiveMessageTool is missing from the module exports. For consistency with the toolkit structure and to match what's stated in the PR description, this tool should also be exported here alongside TelegramSendMessageTool.

Suggested change

from superagi.tools.telegram.telegram_send_message import TelegramSendMessageTool

from superagi.tools.telegram.telegram_send_message import TelegramSendMessageTool

from superagi.tools.telegram.telegram_receive_message import TelegramReceiveMessageTool

Copilot · 2026-01-05T00:23:28Z

superagi/tools/telegram/telegram_receive_message.py

@@ -0,0 +1,68 @@
+from typing import Type, Optional, List


Import of 'Optional' is not used.
Import of 'List' is not used.

Suggested change

from typing import Type, Optional, List

from typing import Type

superagi/tools/telegram/telegram_send_message.py

Fix(Tools): Add chat_id to ReceiveTool output to enable replies

6640dd5

Copilot AI review requested due to automatic review settings January 5, 2026 00:19

Copilot started reviewing on behalf of shanthanu47 January 5, 2026 00:20 View session

Copilot AI reviewed Jan 5, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Feat(Tools): Add Telegram Toolkit with Send/Receive capabilities #1196 #1480

Feat(Tools): Add Telegram Toolkit with Send/Receive capabilities #1196 #1480

Uh oh!

shanthanu47 commented Jan 5, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 5, 2026

Uh oh!

Copilot AI Jan 5, 2026

Uh oh!

Copilot AI Jan 5, 2026

Uh oh!

Copilot AI Jan 5, 2026

Uh oh!

Copilot AI Jan 5, 2026

Uh oh!

Copilot AI Jan 5, 2026

Uh oh!

Copilot AI Jan 5, 2026

Uh oh!

Copilot AI Jan 5, 2026

Uh oh!

Copilot AI Jan 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

-            success message if message is sent successfully or failure message if message sending fails.
+            str: A human-readable message indicating the result of the operation. This may be:
+                - A success message if the message is sent successfully.
+                - A failure message if the Telegram API returns a non-200 status code.
+                - A configuration error message if the TELEGRAM_BOT_TOKEN is not set.
+                - An error message describing any exception raised while sending the message.

-           limit: Number of messages to retrieve.
-        Returns:
-            Recent messages or failure message.
+            limit: Number of messages to retrieve.
+        Returns:
+            str: On success, a single string containing recent text messages, one per line,
+            where each line is formatted as "[chat_id] username: text" and lines are
+            separated by newline characters. On failure, a human-readable error message
+            string such as:
+                - "Error: TELEGRAM_BOT_TOKEN is not set in the configuration."
+                - "Error from Telegram: <description>"
+                - "Failed to retrieve messages. Status Code: <code>. Response: <response body>"
+                - "Error retrieving messages: <exception message>"

	return f"Error retrieving messages: {e}"
	return f"Failed to retrieve Telegram messages due to network or API error: {e}"

	return f"Error sending message: {e}"
	return f"Failed to send Telegram message to chat_id {chat_id} due to network or API error: {e}"

		@@ -0,0 +1,2 @@
		from superagi.tools.telegram.telegram_toolkit import TelegramToolkit
		from superagi.tools.telegram.telegram_send_message import TelegramSendMessageTool

	from superagi.tools.telegram.telegram_send_message import TelegramSendMessageTool
	from superagi.tools.telegram.telegram_send_message import TelegramSendMessageTool
	from superagi.tools.telegram.telegram_receive_message import TelegramReceiveMessageTool

	from typing import Type, Optional, List
	from typing import Type

Feat(Tools): Add Telegram Toolkit with Send/Receive capabilities #1196 #1480

Are you sure you want to change the base?

Feat(Tools): Add Telegram Toolkit with Send/Receive capabilities #1196 #1480

Uh oh!

Conversation

shanthanu47 commented Jan 5, 2026

Description

Changes

Type of change

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 5, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant