tessl/pypi-py-telegram-bot-api
Python Telegram bot API library providing a simple, extensible interface for building Telegram bots with complete Bot API support
—
Pending
chat-management.mddocs/
Chat Management
Chat administration capabilities including member management, permissions, invite links, and chat settings modification.
Capabilities
Chat Information
Retrieve information about chats, members, and administrative status.
def get_chat(self, chat_id: Union[int, str]) -> types.Chat:
"""
Get up-to-date information about a chat.
Parameters:
- chat_id (Union[int, str]): Chat ID or username
Returns:
Chat: Chat information including type, title, member count, etc.
"""
def get_chat_administrators(self, chat_id: Union[int, str]) -> List[types.ChatMember]:
"""
Get list of administrators in a chat.
Parameters:
- chat_id (Union[int, str]): Chat ID or username
Returns:
List[ChatMember]: Array of chat administrators (except other bots)
"""
def get_chat_member_count(self, chat_id: Union[int, str]) -> int:
"""
Get the number of members in a chat.
Parameters:
- chat_id (Union[int, str]): Chat ID or username
Returns:
int: Number of members in the chat
"""
def get_chat_member(self, chat_id: Union[int, str], user_id: int) -> types.ChatMember:
"""
Get information about a chat member.
Parameters:
- chat_id (Union[int, str]): Chat ID or username
- user_id (int): User ID to get information about
Returns:
ChatMember: Member information and status
"""
def leave_chat(self, chat_id: Union[int, str]) -> bool:
"""
Leave a group, supergroup, or channel.
Parameters:
- chat_id (Union[int, str]): Chat ID or username
Returns:
bool: True on success
"""Member Management
Ban, unban, restrict, and promote chat members with granular permissions.
def ban_chat_member(self, chat_id: Union[int, str], user_id: int,
until_date: Optional[Union[int, datetime]] = None,
revoke_messages: Optional[bool] = None) -> bool:
"""
Ban a user from a group, supergroup, or channel.
Parameters:
- chat_id (Union[int, str]): Chat ID or username
- user_id (int): User ID to ban
- until_date (Union[int, datetime], optional): Unban date (unix timestamp or datetime)
- revoke_messages (bool, optional): Delete all messages from the user
Returns:
bool: True on success
"""
def unban_chat_member(self, chat_id: Union[int, str], user_id: int,
only_if_banned: Optional[bool] = False) -> bool:
"""
Unban a previously banned user.
Parameters:
- chat_id (Union[int, str]): Chat ID or username
- user_id (int): User ID to unban
- only_if_banned (bool, optional): Only unban if currently banned
Returns:
bool: True on success
"""
def restrict_chat_member(self, chat_id: Union[int, str], user_id: int,
until_date: Optional[Union[int, datetime]] = None,
can_send_messages: Optional[bool] = None,
can_send_media_messages: Optional[bool] = None,
can_send_polls: Optional[bool] = None,
can_send_other_messages: Optional[bool] = None,
can_add_web_page_previews: Optional[bool] = None,
can_change_info: Optional[bool] = None,
can_invite_users: Optional[bool] = None,
can_pin_messages: Optional[bool] = None) -> bool:
"""
Restrict a user in a supergroup.
Parameters:
- chat_id (Union[int, str]): Chat ID or username
- user_id (int): User ID to restrict
- until_date (Union[int, datetime], optional): Restriction end date
- can_send_messages (bool, optional): Can send text messages
- can_send_media_messages (bool, optional): Can send media
- can_send_polls (bool, optional): Can send polls
- can_send_other_messages (bool, optional): Can send animations, games, stickers
- can_add_web_page_previews (bool, optional): Can add web page previews
- can_change_info (bool, optional): Can change chat info
- can_invite_users (bool, optional): Can invite new users
- can_pin_messages (bool, optional): Can pin messages
Returns:
bool: True on success
"""
def promote_chat_member(self, chat_id: Union[int, str], user_id: int,
can_change_info: Optional[bool] = None,
can_post_messages: Optional[bool] = None,
can_edit_messages: Optional[bool] = None,
can_delete_messages: Optional[bool] = None,
can_invite_users: Optional[bool] = None,
can_restrict_members: Optional[bool] = None,
can_pin_messages: Optional[bool] = None,
can_promote_members: Optional[bool] = None,
is_anonymous: Optional[bool] = None,
can_manage_chat: Optional[bool] = None,
can_manage_voice_chats: Optional[bool] = None) -> bool:
"""
Promote or demote a user in a supergroup or channel.
Parameters:
- chat_id (Union[int, str]): Chat ID or username
- user_id (int): User ID to promote
- can_change_info (bool, optional): Can change chat title, photo, etc.
- can_post_messages (bool, optional): Can create channel posts (channels only)
- can_edit_messages (bool, optional): Can edit messages (channels only)
- can_delete_messages (bool, optional): Can delete messages
- can_invite_users (bool, optional): Can invite new users
- can_restrict_members (bool, optional): Can restrict, ban, or unban members
- can_pin_messages (bool, optional): Can pin messages (supergroups only)
- can_promote_members (bool, optional): Can add new administrators
- is_anonymous (bool, optional): Administrator's presence is hidden
- can_manage_chat (bool, optional): Can access chat event log and statistics
- can_manage_voice_chats (bool, optional): Can manage voice chats
Returns:
bool: True on success
"""Chat Settings
Modify chat appearance, permissions, and configuration.
def set_chat_photo(self, chat_id: Union[int, str], photo) -> bool:
"""
Set a new profile photo for the chat.
Parameters:
- chat_id (Union[int, str]): Chat ID or username
- photo: New chat photo (InputFile)
Returns:
bool: True on success
"""
def delete_chat_photo(self, chat_id: Union[int, str]) -> bool:
"""
Delete a chat photo.
Parameters:
- chat_id (Union[int, str]): Chat ID or username
Returns:
bool: True on success
"""
def set_chat_title(self, chat_id: Union[int, str], title: str) -> bool:
"""
Change the title of a chat.
Parameters:
- chat_id (Union[int, str]): Chat ID or username
- title (str): New chat title (1-255 characters)
Returns:
bool: True on success
"""
def set_chat_description(self, chat_id: Union[int, str], description: Optional[str] = None) -> bool:
"""
Change the description of a supergroup or channel.
Parameters:
- chat_id (Union[int, str]): Chat ID or username
- description (str, optional): New description (0-255 characters)
Returns:
bool: True on success
"""
def set_chat_permissions(self, chat_id: Union[int, str], permissions: types.ChatPermissions) -> bool:
"""
Set default chat permissions for all members.
Parameters:
- chat_id (Union[int, str]): Chat ID or username
- permissions (ChatPermissions): New default permissions
Returns:
bool: True on success
"""Invite Links
Create, edit, revoke, and export chat invite links.
def create_chat_invite_link(self, chat_id: Union[int, str],
expire_date: Optional[Union[int, datetime]] = None,
member_limit: Optional[int] = None) -> types.ChatInviteLink:
"""
Create an additional invite link for a chat.
Parameters:
- chat_id (Union[int, str]): Chat ID or username
- expire_date (Union[int, datetime], optional): Link expiration date
- member_limit (int, optional): Maximum number of users (1-99999)
Returns:
ChatInviteLink: Created invite link
"""
def edit_chat_invite_link(self, chat_id: Union[int, str], invite_link: str,
expire_date: Optional[Union[int, datetime]] = None,
member_limit: Optional[int] = None) -> types.ChatInviteLink:
"""
Edit a non-primary invite link.
Parameters:
- chat_id (Union[int, str]): Chat ID or username
- invite_link (str): The invite link to edit
- expire_date (Union[int, datetime], optional): New expiration date
- member_limit (int, optional): New member limit
Returns:
ChatInviteLink: Edited invite link
"""
def revoke_chat_invite_link(self, chat_id: Union[int, str], invite_link: str) -> types.ChatInviteLink:
"""
Revoke an invite link.
Parameters:
- chat_id (Union[int, str]): Chat ID or username
- invite_link (str): The invite link to revoke
Returns:
ChatInviteLink: Revoked invite link
"""
def export_chat_invite_link(self, chat_id: Union[int, str]) -> str:
"""
Export an invite link to a supergroup or channel.
Parameters:
- chat_id (Union[int, str]): Chat ID or username
Returns:
str: Exported invite link
"""Message Pinning
Pin and unpin messages in chats.
def pin_chat_message(self, chat_id: Union[int, str], message_id: int,
disable_notification: Optional[bool] = False) -> bool:
"""
Pin a message in a supergroup or channel.
Parameters:
- chat_id (Union[int, str]): Chat ID or username
- message_id (int): Message ID to pin
- disable_notification (bool, optional): Don't notify all members
Returns:
bool: True on success
"""
def unpin_chat_message(self, chat_id: Union[int, str], message_id: Optional[int] = None) -> bool:
"""
Unpin a specific pinned message in a supergroup.
Parameters:
- chat_id (Union[int, str]): Chat ID or username
- message_id (int, optional): Message ID to unpin (if not specified, unpins most recent)
Returns:
bool: True on success
"""
def unpin_all_chat_messages(self, chat_id: Union[int, str]) -> bool:
"""
Unpin all pinned messages in a supergroup.
Parameters:
- chat_id (Union[int, str]): Chat ID or username
Returns:
bool: True on success
"""Usage Examples
Basic Chat Management
# Get chat information
chat = bot.get_chat("@mychannel")
print(f"Chat title: {chat.title}")
print(f"Member count: {bot.get_chat_member_count(chat.id)}")
# Get administrators
admins = bot.get_chat_administrators(chat.id)
for admin in admins:
print(f"Admin: {admin.user.first_name}")Member Moderation
@bot.message_handler(commands=['ban'])
def ban_user(message):
if message.reply_to_message:
user_id = message.reply_to_message.from_user.id
bot.ban_chat_member(message.chat.id, user_id)
bot.reply_to(message, "User banned!")
@bot.message_handler(commands=['restrict'])
def restrict_user(message):
if message.reply_to_message:
user_id = message.reply_to_message.from_user.id
bot.restrict_chat_member(
message.chat.id,
user_id,
can_send_messages=False,
until_date=datetime.now() + timedelta(hours=1)
)
bot.reply_to(message, "User restricted for 1 hour!")Chat Settings Management
@bot.message_handler(commands=['settitle'])
def set_title(message):
args = message.text.split(maxsplit=1)
if len(args) > 1:
new_title = args[1]
bot.set_chat_title(message.chat.id, new_title)
bot.reply_to(message, f"Title changed to: {new_title}")
@bot.message_handler(commands=['pin'])
def pin_message(message):
if message.reply_to_message:
bot.pin_chat_message(message.chat.id, message.reply_to_message.message_id)
bot.reply_to(message, "Message pinned!")Types
class Chat:
id: int
type: str # 'private', 'group', 'supergroup', 'channel'
title: Optional[str]
username: Optional[str]
first_name: Optional[str]
last_name: Optional[str]
photo: Optional[ChatPhoto]
bio: Optional[str]
description: Optional[str]
invite_link: Optional[str]
pinned_message: Optional[Message]
permissions: Optional[ChatPermissions]
# ... additional fields
class ChatMember:
user: User
status: str # 'creator', 'administrator', 'member', 'restricted', 'left', 'kicked'
custom_title: Optional[str]
is_anonymous: Optional[bool]
until_date: Optional[int]
# ... permission fields
class ChatPermissions:
can_send_messages: Optional[bool]
can_send_media_messages: Optional[bool]
can_send_polls: Optional[bool]
can_send_other_messages: Optional[bool]
can_add_web_page_previews: Optional[bool]
can_change_info: Optional[bool]
can_invite_users: Optional[bool]
can_pin_messages: Optional[bool]
class ChatInviteLink:
invite_link: str
creator: User
creates_join_request: bool
is_primary: bool
is_revoked: bool
name: Optional[str]
expire_date: Optional[int]
member_limit: Optional[int]
pending_join_request_count: Optional[int]Install with Tessl CLI
npx tessl i tessl/pypi-py-telegram-bot-api