agentconnect.agents.telegram.telegram_tools module

Telegram-specific tools for use with the AgentConnect framework.

This module defines tools that enable an AI agent to interact with Telegram, manage announcements, handle user groups, and send messages using advanced aiogram v3 capabilities.

class SendMessageInput(**data)

Bases: BaseModel

Input schema for sending a message to Telegram.

Parameters:

• chat_id (int)

• text (str)

• reply_to_message_id (int | None)

• parse_mode (str | None)

chat_id: int

text: str

reply_to_message_id: Optional[int]

parse_mode: Optional[str]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class SendMessageOutput(**data)

Bases: BaseModel

Output schema for sending a message to Telegram.

Parameters:

• success (bool)

• message_id (int | None)

• error (str | None)

success: bool

message_id: Optional[int]

error: Optional[str]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class SendPhotoInput(**data)

Bases: BaseModel

Input schema for sending a photo to Telegram.

Parameters:

• chat_id (int)

• photo_url (str)

• caption (str | None)

• reply_to_message_id (int | None)

chat_id: int

photo_url: str

caption: Optional[str]

reply_to_message_id: Optional[int]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class SendPhotoOutput(**data)

Bases: BaseModel

Output schema for sending a photo to Telegram.

Parameters:

• success (bool)

• message_id (int | None)

• error (str | None)

success: bool

message_id: Optional[int]

error: Optional[str]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class SendDocumentInput(**data)

Bases: BaseModel

Input schema for sending a document to Telegram.

Parameters:

• chat_id (int)

• document_url (str)

• caption (str | None)

• reply_to_message_id (int | None)

chat_id: int

document_url: str

caption: Optional[str]

reply_to_message_id: Optional[int]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class SendDocumentOutput(**data)

Bases: BaseModel

Output schema for sending a document to Telegram.

Parameters:

• success (bool)

• message_id (int | None)

• error (str | None)

success: bool

message_id: Optional[int]

error: Optional[str]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class SendLocationInput(**data)

Bases: BaseModel

Input schema for sending a location to Telegram.

Parameters:

• chat_id (int)

• latitude (float)

• longitude (float)

• reply_to_message_id (int | None)

chat_id: int

latitude: float

longitude: float

reply_to_message_id: Optional[int]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class SendLocationOutput(**data)

Bases: BaseModel

Output schema for sending a location to Telegram.

Parameters:

• success (bool)

• message_id (int | None)

• error (str | None)

success: bool

message_id: Optional[int]

error: Optional[str]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class SendVoiceInput(**data)

Bases: BaseModel

Input schema for sending a voice message to Telegram.

Parameters:

• chat_id (int)

• voice_url (str)

• caption (str | None)

• reply_to_message_id (int | None)

chat_id: int

voice_url: str

caption: Optional[str]

reply_to_message_id: Optional[int]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class SendVoiceOutput(**data)

Bases: BaseModel

Output schema for sending a voice message to Telegram.

Parameters:

• success (bool)

• message_id (int | None)

• error (str | None)

success: bool

message_id: Optional[int]

error: Optional[str]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class DownloadFileInput(**data)

Bases: BaseModel

Input schema for downloading a file from Telegram.

Parameters:

file_id (str)

file_id: str

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class DownloadFileOutput(**data)

Bases: BaseModel

Output schema for downloading a file from Telegram.

Parameters:

• success (bool)

• file_path (str | None)

• content_type (str | None)

• file_size (int | None)

• error (str | None)

success: bool

file_path: Optional[str]

content_type: Optional[str]

file_size: Optional[int]

error: Optional[str]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class CreateAnnouncementInput(**data)

Bases: BaseModel

Input schema for creating an announcement.

Parameters:

• text (str)

• photo_url (str)

text: str

photo_url: str

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class CreateAnnouncementOutput(**data)

Bases: BaseModel

Output schema for creating an announcement.

Parameters:

• announcement_id (str)

• text (str)

• photo_url (str | None)

announcement_id: str

text: str

photo_url: Optional[str]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class PublishAnnouncementInput(**data)

Bases: BaseModel

Input schema for publishing an announcement to groups.

Parameters:

• announcement_id (str)

• groups (List[int])

announcement_id: str

groups: List[int]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class PublishAnnouncementOutput(**data)

Bases: BaseModel

Output schema for publishing an announcement.

Parameters:

• success (bool)

• sent_to_groups (List[int])

• failed_groups (List[Dict[str, Any]])

success: bool

sent_to_groups: List[int]

failed_groups: List[Dict[str, Any]]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ListGroupsInput(**data)

Bases: BaseModel

Input schema for listing registered groups.

Parameters:

limit (int)

limit: int

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class ListGroupsOutput(**data)

Bases: BaseModel

Output schema for listing registered groups.

Parameters:

• groups (List[Dict[str, Any]])

• total (int)

groups: List[Dict[str, Any]]

total: int

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class DeleteAnnouncementInput(**data)

Bases: BaseModel

Input schema for deleting a draft announcement.

Parameters:

announcement_id (str)

announcement_id: str

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class DeleteAnnouncementOutput(**data)

Bases: BaseModel

Output schema for deleting an announcement.

Parameters:

• success (bool)

• error (str | None)

success: bool

error: Optional[str]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class EditMessageInput(**data)

Bases: BaseModel

Input schema for editing a message.

Parameters:

• chat_id (int)

• message_id (int)

• text (str)

chat_id: int

message_id: int

text: str

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class EditMessageOutput(**data)

Bases: BaseModel

Output schema for editing a message.

Parameters:

• success (bool)

• error (str | None)

success: bool

error: Optional[str]

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class TelegramTools(bot, group_ids, groups_file)

Bases: object

Contains tools for interacting with Telegram through the AgentConnect framework.

This class provides tools for sending messages, managing announcements, and interacting with Telegram users and groups.

Parameters:

• bot (Bot)

• group_ids (Set[int])

• groups_file (str)

async send_message(chat_id, text, reply_to_message_id=None, parse_mode=None)

Send a text message to a Telegram chat.

IMPORTANT: DO NOT USE THIS FOR RESPONDING TO THE USER WHO SENT THE CURRENT MESSAGE. This tool should ONLY be used when you need to send a message to a DIFFERENT chat/group than the one where the current conversation is happening.

For normal responses to the user, just return your response text directly in your reply.

Parameters:

• chat_id (int) – Telegram chat ID to send message to (must be different from current chat)

• text (str) – Text message to send

• reply_to_message_id (Optional[int]) – Optional message ID to reply to

• parse_mode (Optional[str]) – Parse mode for the message

Return type:

Dict[str, Any]

Returns:

Dict with success status and message ID or error

async send_photo(chat_id, photo_url, caption=None, reply_to_message_id=None)

Send a photo to a Telegram chat.

Parameters:

• chat_id (int) – Telegram chat ID

• photo_url (str) – URL or file_id of the photo

• caption (Optional[str]) – Optional caption for the photo

• reply_to_message_id (Optional[int]) – Optional message ID to reply to

Return type:

Dict[str, Any]

Returns:

Dict with success status and message ID or error

async send_document(chat_id, document_url, caption=None, reply_to_message_id=None)

Send a document to a Telegram chat.

Parameters:

• chat_id (int) – Telegram chat ID

• document_url (str) – URL or file_id of the document

• caption (Optional[str]) – Optional caption for the document

• reply_to_message_id (Optional[int]) – Optional message ID to reply to

Return type:

Dict[str, Any]

Returns:

Dict with success status and message ID or error

async send_location(chat_id, latitude, longitude, reply_to_message_id=None)

Send a location to a Telegram chat.

Parameters:

• chat_id (int) – Telegram chat ID

• latitude (float) – Latitude of the location

• longitude (float) – Longitude of the location

• reply_to_message_id (Optional[int]) – Optional message ID to reply to

Return type:

Dict[str, Any]

Returns:

Dict with success status and message ID or error

async send_voice(chat_id, voice_url, caption=None, reply_to_message_id=None)

Send a voice message to a Telegram chat.

Parameters:

• chat_id (int) – Telegram chat ID

• voice_url (str) – URL or file_id of the voice

• caption (Optional[str]) – Optional caption for the voice message

• reply_to_message_id (Optional[int]) – Optional message ID to reply to

Return type:

Dict[str, Any]

Returns:

Dict with success status and message ID or error

async download_file(file_id)

Download a file from Telegram.

Parameters:

file_id (str) – Telegram file ID

Return type:

Dict[str, Any]

Returns:

Dict with download information

async edit_message(chat_id, message_id, text)

Edit an existing message.

Parameters:

• chat_id (int) – Telegram chat ID

• message_id (int) – ID of the message to edit

• text (str) – New text for the message

Return type:

Dict[str, Any]

Returns:

Dict with success status or error

async create_announcement(text, photo_url='')

Create a new announcement.

Parameters:

• text (str) – Announcement text content

• photo_url (str) – URL or file_id for an announcement image. Empty string for text-only announcement.

Return type:

Dict[str, Any]

Returns:

Dict with announcement details

async publish_announcement(announcement_id, groups=None)

Publish an announcement to groups.

Parameters:

• announcement_id (str) – ID of the announcement to publish

• groups (List[int]) – List of specific group IDs to publish to. If empty, publishes to all groups.

Return type:

Dict[str, Any]

Returns:

Dict with publishing results

async list_groups(limit=10)

List registered groups.

Parameters:

limit (int) – Maximum number of groups to return

Return type:

Dict[str, Any]

Returns:

Dict with list of groups and total count

async delete_announcement(announcement_id)

Delete a draft announcement.

Parameters:

announcement_id (str) – ID of the announcement to delete

Return type:

Dict[str, Any]

Returns:

Dict with deletion status

get_langchain_tools()

Get a list of LangChain tools for Telegram operations.

Return type:

List[StructuredTool]

Returns:

List of StructuredTool instances