Наконец снова добрались руки до api MAX, а конкретно - до минимального управления группой. Тут вряд ли будет что-то супер сложное, но мы точно поговорим об одном баге (возможно - о фиче).
Спойлер: в следующей статье будем разбираться, как копировать новые посты из телеграмм канала в макс, но об этой боли позже.
Сегодня пройдемся по базовому функционалу групп.
Получение информации о чате
Еще недавно можно было получить информацию о чате через пригласительную ссылку. Теперь нам доступен только метод запроса через id - bot.get_chat_by_id()
В выводе мы получим поля:
chat_id - ID группового чата
title - Название чата
participants_count - Количество участников
owner_id - ID владельца группы
participants - Словарь с ID пользователей и временем их вступления в формате datetime
link - Пригласительная ссылка
Важное уточнение: в participants мы получим только список активных пользователей. Заблокированные в этот список не попадают.
Добавление пользователя в группу через бота
Мы уже научились обрабатывать deeplink'и и callback'и, поэтому предлагаю сразу написать простенькую обработку для вступления в группу.
Логика простая: пользователь переходит по ссылке на бота, принимает согласие, и бот добавляет его в группу.
Как и в предыдущей статье, практически ничего не изменилось.
Также добавляем обработчик callback:
callback.answer(notification='passed') - Пользователю выдаст уведомление с текстом "passed" (как всплывающее сообщение в самом мессенджере)
callback.message.edit(attachments=[], text='Я добавил Вас в группу') - Бот изменит предыдущее сообщение, удалив при этом клавиатуру (чтобы не было повторного нажатия)
bot.add_chat_members(chat_id=group_id, user_ids=[callback.from_user.user_id]) - Бот добавит пользователя в группу.
Важно: при добавлении пользователей в группу, в user_ids нужно передавать список (даже если добавляете только одного пользователя)
Если у вас будет дополнительная логика, перед добавлением неплохо бы искать пользователя в группе, чтобы не было, например, задвоения записей в СУБД. В нашем случае все просто: если пользователь уже в группе, ничего не произойдет.
Удаление пользователя из группы
За удаление из группы отвечает функция bot.kick_chat_member(), в которую необходимо передать id группы, из которой мы удаляем пользователя, и id самого пользователя.
При необходимости, можно также блокировать пользователю вход, передавая дополнительный параметр "block=True":
При блокировке пользователя, он отобразится в списке заблокированных в группе:
И вот тут важно сразу дать уточнение: если вы полностью хотите заблокировать пользователя, нужно маркер блокировки хранить где-то еще.
Если вы блокируете пользователю доступ через bot.kick_chat_member(chat_id=group_id, user_id=user_id, block=True), он попадает в список заблокированных, но bot.add_chat_members игнорирует список заблокированных, добавляя пользователя обратно.
Тут два пути: либо вход в группу по одноразовым QR кодам с проверкой из вашей CRM, либо добавления id пользователя в СУБД при блокировке.
Получение списка участников группы
Недавно мы разбирались, как сделать массовую отправку сообщений. Проще говоря - рассылку.
Но чтобы создать рассылку, нам нужен список получателей. Предположим, мы хотим отправить каждому участнику нашей группы персональное сообщение. Если пользователи заходили в группу, или канал через бота, у них остался с ботом чат, поэтому подозреваем, что он может отправить сообщения.
За вывод всех участников группы отвечает bot.get_chat_members(). В вывод этой функции попадает json "members=[список участников]"
Выглядеть каждая запись будет примерно так:
ChatMember(user_id=11111, first_name='имя', last_name='фамилия', username=None, is_bot=False, last_activity_time=1772394825000, description=None, commands=None, last_access_time=1772394805234, is_owner=True, is_admin=True, join_time=1770029846639, permissions=[<ChatPermission.ADD_REMOVE_MEMBERS: 'add_remove_members'>, <ChatPermission.CAN_CALL: 'can_call'>, <ChatPermission.ADD_ADMINS: 'add_admins'>, <ChatPermission.PIN_MESSAGE: 'pin_message'>, <ChatPermission.DELETE: 'delete'>, <ChatPermission.VIEW_STATS: 'view_stats'>, <ChatPermission.EDIT_LINK: 'edit_link'>, <ChatPermission.READ_ALL_MESSAGES: 'read_all_messages'>, <ChatPermission.WRITE: 'write'>, <ChatPermission.CHANGE_CHAT_INFO: 'change_chat_info'>, <ChatPermission.EDIT: 'edit'>], alias=None)]
Нас интересуют поля:
user_id - id пользователя
first_name - Имя пользователя
is_admin - Маркер, админ ли пользователь
Последний пункт субъективен. Я подозреваю, что нам не нужно отправлять сообщения администраторам канала, а в список получателей должны попасть только пользователи. Также, если в канале больше одного бота, неплохо бы фильтровать по ключу "is_bot".
Немного доработаем нашу функцию:
Теперь на выходе мы будем получать список формата:
[{'id': userid1, 'name': 'user_name_1'}, {'id': userid2, 'name': 'user_name_2'}]