Бот авторизаций в Telegram для корпоративных чатов27.06.2024 16:00

Привет, я Саша Снытко, и я руковожу командой BI в Data Office Tele2. Мы уже рассказывали здесь о миграции на Fine BI, если быть точнее, о нашем опыте мониторинга пользователей. Сегодня речь пойдет о кардинально другой теме — разработке Telegram-бота для корпоративных каналов и чатов. Задача, которая родилась из потребности следить за составом подписчиков чата Data Office и выросла в полноценный корпоративный инструмент.

В статье мы с главным разработчиком нашего бота (спойлер: стажером команды, которая проявила инициативу и вызвалась заняться этой нетривиальной задачкой) рассказываем о своем опыте разработки в Telegram API на основе библиотек Telebot и Telethon. Еще объясним, как смогли обойти ограничение Telegram по выгрузке в 200 пользователей и настроили интеграцию с корпоративным LDAP-каталогом. Ну и куда без дашборда статистики активности Tg-каналов в Fine BI. В свое время нам не хватило прикладного DIY-материала, и мы проходили весь путь с граблями и шишками самостоятельно. Надеемся, что эта статья поможет кому-то из вас. А те, кто уже прошел этот путь, подскажут нам новые пути решения и возможности апгрейднуть наш сервис.

Летопись от рождения Data Office Tele2

Никого не удивим, если скажем, что, попадая в сеть, информация остается в ней навсегда. Даже параметр «чат доступен ограниченному кругу пользователей» не защищает от сливов и утечек. Мы это понимали с самого создания наших корпоративных чата и канала в Telegram: чат был создан в 2022 году для общения BI-пользователей и поддержания миграции на Fine BI, а канал для автоматического информирования наших коллег о текущих инцидентах качества данных — еще во времена ковида в 2020 году. Важно отметить, что у нас, конечно же, есть корпоративный мессенджер и стандарты коммуникаций в компании, к которым у нас как у пользователей нет вопросов. Но в данном случае мы просто решили не плыть против течения и не пытаться одолеть один из самых удобных и привычных для наших пользователей мессенджеров в мире.

По мере увеличения числа подписчиков и изменений в их корпоративном статусе (люди нанимаются и увольняются, сами понимаете) росла и потребность в мониторинге членства именно сотрудников. Мы тщательно следим за соблюдением правил в нашем сообществе в Telegram (не делимся чувствительной информацией ни в каком из ее видов, не обсуждаем коммерческую информацию и не упоминаем абонентские данные даже всуе). И тем не менее все, что происходит на нашей площадке, должно остаться на нашей площадке — вопрос приватности обсуждаемых тем для нас всегда актуален.

Когда мы перевалили отметку в 300 подписчиков, вопрос безопасности встал наиболее остро, и пришло время что-то с этим делать. Наша главная цель — быть уверенными, что доступ к публикациям и перепискам имеют только действующие сотрудники Tele2. Помимо этого, мы хотели дать возможность администраторам следить за динамикой развития ресурса, понимать, среди каких подразделений и сотрудников он популярен.

Поэтому мы приступили к разработке бота. Функция ясна — он должен был стать точкой верификации действующих подписчиков и авторизации новых.

Почему так? Сейчас расскажу.

В нашем случае внедрение бота произошло сильно позже создания и канала, и чата. В обеих сущностях уже имелся достаточно массивный архив диалогов и материалов, была своя история. Такая летопись развития Data Office в компании с фотографиями, анонсами, бурными обсуждениями и решениями. Поэтому вариант «удалить все и переехать в новые сущности» мы отмели сразу, хотя и понимали, что это было бы в разы проще и для подписчиков, и для нас.

Итак, мы определили, что нам потребуется подключать бот к уже существующим каналу и чату. Он должен будет (как-то) произвести чистку всех неактуальных подписчиков (не-сотрудников компании, удаленных аккаунтов) или как минимум помочь нам в этом. Также в дальнейшем он должен стать точкой входа в канал — таким «вышибалой» на входе в сообщество (также на основе параметра принадлежности к компании).

Первые шаги

Мы начали искать информацию в интернете и ИТ-сообществе. К сожалению, все, что мы нашли, было описано поверхностно и разбросано кусками по разным источникам. Однозначного ответа или последовательного DIY не было. Тогда мы поняли, что придется попотеть, и начали шаг за шагом двигаться самостоятельно.

Кстати, как и упомянул в самом начале, хотя эта статья написана мной, вопрос разработки бота — от поиска путей до финальных корректировок и раскатки на другие корпоративные чаты и каналы — мы полностью доверили тогда еще стажеру нашей BI-команды, а сейчас уже полноценному и очень ценному специалисту Соне. Можно сказать, что эта задача стала ее корпоративным pet-проектом. Я же был идейным вдохновителем и, как это обычно бывает, площадкой для валидации решений и предложений Сони.

Но вернемся к техническому сторителлингу.

Сервисная разработка не является нашей специализацией, но мы не хотели стоять в очереди в соответствующий ИТ-отдел компании с приоритизацией наших идей. Поэтому решили использовать подручные инструменты — Python и две библиотеки, основанные на Telegram Bot API и Telegram API (Telebot и Telethon).

Telegram Bot API предназначен исключительно для разработки ботов — специальных аккаунтов с пометкой «bot» в юзернейме, не требующих дополнительной авторизации по номеру телефона. Несмотря на то, что наш бот является именно таким аккаунтом, возможностей, предоставляемых этим видом API, нам не хватало. Поэтому для части функционала мы используем библиотеку Telethon, работающую из-под Telegram API. Такой подход позволяет создавать свои собственный клиент Telegram и требует авторизацию (привязку реального аккаунта) по номеру телефона. Запуск клиента все еще возможен от имени бота, поэтому мы можем управлять им с использованием одновременно и Bot API, и Telegram API.

Разберем основной функционал нашего бота и его реализацию.

Создание бота и клиента Telegram

Для создания своего бота необходимо в Telegram написать команду /newbot в личные сообщения боту @BotFather. Он запросит имя и юзернейм для будущего бота, а затем пришлет токен — уникальный идентификатор, использующийся в коде для авторизации бота.

Для использования библиотеки Telebot этого достаточного. Код для начала управления ботом через Bot API выглядит так:

import Telebot

token=’your_token’
bot=telebot.TeleBot(token)

Для запуска клиента Telegram в соответствии с требованиями Telegram API необходимо получить уникальные api_id и api_hash, привязанные к аккаунту разработчика. Это можно сделать здесь.

С помощью библиотеки Telethon клиент запускается так:

import Telethon
client = telethon.TelegramClient('session', api_id, api_hash, proxy=proxy
                                 ).start(bot_token=bot_token)

Выше необходимо задать переменные api_id, api_hash, bot_token и при необходимости proxy (в нашем корпоративном кейсе без этого никак). Также можно не использовать аргумент bot_token — тогда все действия будут исполняться из-под вашего аккаунта. При первом запуске сессии вам может понадобиться ввести свой номер телефона и пришедший на него код.

В нашем случае библиотеки Telebot и Telethon используются в двух разных скриптах, управляющих ботом независимо друг от друга.

Подключение к базе данных

Для регистрации Telegram-аккаунтов сотрудников в нашем сервисе и проверки их статуса в компании необходимо подключиться к базе данных, в которой хранится информация о сотрудниках и в которую мы будем записывать регистрации пользователей и данные наших чатов.

БД могут быть любыми, а для работы с ними в Python обычно есть специальные библиотеки. Мы, например, использовали cx_Oracle.

import cx_Oracle

cx_Oracle.init_oracle_client(
    lib_dir=r"path")#Прописываем путь до скачанного на локальной машине клиента Oracle 
connection = cx_Oracle.connect(user="**", password=userpwd,
                               dsn="dbhost.example.com/orclpdb1",
                               encoding="UTF-8") #Подключаемся к БД
cursor = oracle_connection.cursor()

Подробнее о подключении к базе данных можно прочитать в документации библиотеки.

Структура базы данных

Мы хотим собирать данные зарегистрированных пользователей и иметь возможность анализировать развитие Telegram-чатов компании. На данный момент мы используем четыре таблицы с данными пользователей и чатов:

TG_CHATS_USERS (Историчные данные об участниках всех чатов):

TG_CHATS_CURRENT_USERS (только актуальные данные о действующих участниках чатов):

TG_ACTIVE_USERS (актуальные данные о всех регистрациях):

TG_CHATS (историчные данные о чатах и каналах):

TG_CHATS_INFO (актуальные данные о чатах и каналах):

Данные с номерами сотрудников мы берем из корпоративного LDAP-каталога компании. На первом этапе нам было проще организовать хранение этих данных в виде таблицы в БД. В дальнейшем наверняка переведем все на API. Так, при проверке статуса пользователя в компании, мы обращаемся к таблице T_AD_USERS_PHONES.

Регистрация сотрудника (пользователя)

Перед предоставлением доступа к корпоративным ресурсам в Telegram мы хотим убедиться, что пользователь является действующим сотрудником компании. Для проверки мы используем функцию «поделиться контактом» — номер телефона, на который зарегистрирован аккаунт в Telegram, должен совпадать с одним из номеров сотрудника в Active Directory (в нашем случае это основной или дополнительный номер, указанный сотрудником в корпоративном личном кабинете). Данные успешно зарегистрированного сотрудника записываются в таблицу в БД, которая в дальнейшем используется для одобрения заявок на вступление в чаты и аналитики развития нашего коммьюнити в Telegram.

При получении в личных сообщениях команды /start от пользователя бот запрашивает его контакт — у пользователя появляется кнопка «Поделиться контактом».

@bot.message_handler(commands=['start'])
def start(message):
    keyboard = types.ReplyKeyboardMarkup(row_width=1, resize_keyboard=True)
    button_phone = types.KeyboardButton(text="Поделиться контактом", request_contact=True)
    keyboard.add(button_phone)
    bot.send_message(message.chat.id, "Текст сообщения”) #Отправляет сообщение пользователю

Со стороны пользователя эта функция нашего бота выглядит так:

После получения контакта пользователя происходит поиск указанного номера в таблице БД с номерами телефонов и поиск id пользователя (message.chat.id) в таблице TG_ACTIVE_USERS. Так мы проверяем, является ли пользователь действующим сотрудником компании и нет ли у него уже активной регистрации.

@bot.message_handler(content_types=['contact'])
def read_contact_phone(message):
 	phone = int(message.contact.phone_number)
 	user_id = message.from_user.id
 	usname = message.from_user.username
 	first_name = message.from_user.first_name
             last_name = message.from_user.last_name
cursor.execute("SELECT MSISDN as MOBILE FROM dic.t_ad_users_phones")
      allow_df = pd.DataFrame(cursor.fetchall(), columns=['MOBILE'])
      cursor.execute('SELECT ID from biteam.TG_ACTIVE_USERS where ENABLED=1')
      user_df=pd.DataFrame(cursor.fetchall(), columns=['ID'])

Условия для успешного завершения регистрации — привязанный к аккаунту номер телефона указан в LDAP-каталоге, у пользователя пока что нет активной регистрации (он не находится в датафрейме user_df), и он поделился действительно своим контактом.

if phone in allowed and user_id not in user_df['ID'].to_list() and message.contact.user_id == message.from_user.id:

    bot.send_message(user_id, 'Вы успешно прошли регистрацию')

На этом этапе мы также записываем в БД данные зарегистрировавшего пользователя. Можно использовать не только ID, но и указанные в Telegram имя, фамилию, username — все, что кажется вам необходимым.

Внутри этого же условия происходит одобрение всех заявок на вступление, поданных пользователем до регистрации в боте. О том, как это реализовано — расскажем чуть позже.

Мы предусматриваем ответы пользователю в случае несоблюдения какого-либо из условий:

elif message.contact.user_id != message.from_user.id:
    bot.send_message(user_id, 'Поделитесь своим контактом, а не чужим')
elif phone in allowed and user_id in user_df['ID'].to_list():
    bot.send_message(user_id, 'Вы уже зарегистрированы как сотрудник Tele2')
else:
    bot.send_message(user_id, 'Вы не прошли верификацию. Если вы являетесь сотрудником Tele2, убедитесь, что ваш номер телефона указан в Intranet')

Регистрация чата или канала

Для корректной работы бота с чатами необходимо назначить его администратором соответствующего чата. В нашем случае требуется еще одно действие — отправка команды /regchat в личные сообщения боту. В этом случае мы заносим данные о новом подключенном чате в таблицу TG_CHATS и справочник TG_CHATS_INFO. В них же фиксируется количество участников чата или канала. Данные обновляются по команде /update, принцип работы которой мы опишем позже.

На вход функция принимает сообщение с текстом, содержащим команду »/regchat», далее должен быть прописан id чата или канала. Затем бот запрашивает новое имя для чата и заносит данные в таблицу (вложенная функция regchats_step2). Регистрирующий чат пользователь должен быть его администратором или создателем.

@bot.message_handler(commands=['regchat'])
def regchats(message):

    def regchats_step2(message):
        chat_name = message.text
        if message.text == '/back':
            bot.send_message(author,'Вы вернулись в основное меню')
        else:
 		cursor.execute("INSERT INTO TG_CHATS (CHAT_ID, CHAT_NAME, CHAT_TITLE, MEMBERS_CNT) VALUES (:chat_id, :chat_name, :chat_title, :member_cnt)", [group_chat_id, chat_name, chat_title, member_cnt])
            oracle_connection.commit()

            cursor.execute("DELETE FROM TG_CHATS_INFO WHERE CHAT_ID=:chat_id", [group_chat_id])
            cursor.execute("INSERT INTO TG_CHATS_INFO (CHAT_ID, CHAT_NAME, CHAT_TITLE, MEMBERS_CNT, CHAT_TYPE) VALUES (:chat_id, :chat_name, :chat_title, :member_cnt, :chat_type)", [group_chat_id, chat_name, chat_title, member_cnt, chat_type])
            oracle_connection.commit()
            bot.send_message(author,f'Ваш чат зарегистрирован под названием {chat_name}')

    author = message.from_user.id
    try:
        group_chat_id = int(message.text[8:])
        print(group_chat_id)
        status = bot.get_chat_member(group_chat_id, author).status

        cursor.execute('SELECT ID where ENABLED=1') 
 	  reg_user_df=pd.DataFrame(cursor.fetchall(), columns=['ID'])
        reg_id = list(reg_user_df.ID)

        if (status in ['creator', 'administrator'] and author in reg_id) or author==402704588:
            bot.send_message(author,'Как вы хотите назвать чат?\n \n Чтобы отменить регистрацию чата напишите /back')
            chat_title=bot.get_chat(group_chat_id).title
            member_cnt=bot.get_chat_members_count(group_chat_id)
            chatt = bot.get_chat(group_chat_id)
            chat_type=chatt.type
            bot.register_next_step_handler(message, regchats_step2)

        else:
            bot.send_message(author,'Вы должны быть зарегистрированы как сотрудник и являться администратором чата или канала')
    except:
         bot.send_message(author,'Убедитесь, что id чата или канала корректен')

Прием заявок на вступление

Контроль за доступом к чатам и каналам обеспечен предварительной проверкой новых участников. Чтобы присоединиться к новому чату, пользователь должен предварительно пройти регистрацию. При получении новой заявки на вступление мы проверяем, есть ли актуальная регистрация у пользователя. В случае, если данные о регистрации пользователя находятся в таблице TG_ACTIVE_USERS, его заявки принимаются автоматически. Иначе бот отправляет сообщение пользователю о необходимости пройти регистрацию.

@bot.chat_join_request_handler()
def join_requests(message):
    global req
    req = message
    user_id=int(message.from_user.id)
    usname = message.from_user.username
    first_name = message.from_user.first_name
    last_name = message.from_user.last_name

Мы используем глобальную переменную req, так как в дальнейшем она будет применяться в функции регистрации пользователей. После удачного завершения регистрации все активные заявки на вступление в корпоративные чаты и каналы будут приняты.

    cursor.execute('SELECT ID from TG_ACTIVE_USERS where ENABLED=1')
    user_df=pd.DataFrame(cursor.fetchall(), columns=['ID'])
    user_df['ID'] = user_df['ID'].astype(int)
    if user_id in list(user_df['ID']):
        bot.approve_chat_join_request(message.chat.id, user_id)
        bot.send_message(user_id, 'Вы успешно авторизовались и ваша заявка принята')
    else:
        bot.send_message(user_id, 'Для доступа к корпоративным каналам и чатам вам необходимо авторизоваться.'
                                  'Напишите /start.')

Зарегистрированные пользователи сразу добавляются в желаемый чат, а в таблицу TG_CHATS_USERS мы отдельно включаем строку о присутствии пользователя в чате.

Как мы уже отметили, переменная req является глобальной и используется в уже описанной выше функции обработки контакта. Поэтому в эту функцию мы также добавляем одобрение всех активных заявок на вступление в чаты и каналы.

try:
    bot.approve_chat_join_request(req.chat.id, user_id)
CHAT_USERS
except:
    bot.send_message(user_id, 'На данный момент у вас нет заявок на вступление в каналы')

Мы также записываем данные о вступлении пользователя в чат в таблицу TG_CHATS_USERS. Если вы хотите отслеживать, кто именно присутствует в определенных чатах и каналах, вы можете делать то же самое.

Немного о командах

Команда /update

Команда /update используется администраторами чатов и каналов для обновления в таблицах актуальных данных о состоянии чатов и присоединившихся к ним пользователях. На вход функция принимает сообщение с текстом, содержащим команду »/update», далее должен быть прописан id чата или канала. Аналогично обработке команды /regchat мы проверяем, зарегистрирован ли пользователь и является ли он администратором группы.

Эта функция работает в отдельном скрипте с использованием библиотеки Telethon. Применявшийся раннее Telegram Bot API не дает возможности разом получить всех участников чата, что является необходимым для нашей задачи. Поэтому мы обращаемся к самому Telegram API.

Мы собираем список всех участников чата или канала, а затем сверяем его с данными, которые есть у нас. Если что-то изменилось (появились новые подписчики, кто-то сменил имя или фамилию в Telegram, покинул чат) — вносим обновления в нашу БД. Для каждого пользователя мы также проверяем, зарегистрирован ли он (есть ли данные о нем в таблице TG_ACTIVE_USERS) и проставляем соответствующий признак.

Собрать информацию об актуальных подписчиках через Telethon можно так:

participants = client.iter_participants(group_id)
                    all_user_ids=[]

                 # Цикл по всем участникам группы
                    async for participant in participants:
                        if not participant.deleted:
                            user_id=participant.id
                            #user_mobile=словарь.get(id)
                            username=participant.username
                            first_name=participant.first_name
                            last_name=participant.last_name
                            if type(participant.participant) == ChannelParticipantAdmin:
                                status='admin'
                            elif type(participant.participant) == ChannelParticipantCreator:
                                status='creator'
                            else:
                                status='member'

Так мы можем собрать всю интересующую нас информацию о всех пользователях, а далее записать в БД. Помимо обновления таблицы TG_CHATS_USERS мы обновляем еще и TG_CHATS и справочник TG_CHATS_INFO — актуализируем количество подписчиков группы или канала.

Команда /kick

Команда /kick используется администраторами чатов и каналов аналогично командам /update и /regchat. Функция принимает на вход сообщение с текстом, содержащим »/kick» и id чата или канала.

Как и раньше, мы собираем ID всех участников чата и сравниваем с уже имеющимися у нас данными. Проходим циклом по всем пользователям и, если кто-то из них не зарегистрирован или больше не является сотрудником компании, удаляем его из чата.

await client.kick_participant(group_id, user_id)

Для проверки наличия регистрации мы обращаемся к таблице TG_ACTIVE_USERS, а для проверки статуса в компании сравниваем номер телефона с хранящимися в AD_USERS_PHONES.

Ограничения Telegram на парсинг пользователей

Разрабатывая бота, мы наткнулись на ограничения Telegram API — можно спарсить только первых 200 подписчиков каждого канала. Это ограничение не распространяется на группы и не мешает модерировать небольшие каналы, в которых меньше 200 подписчиков. Но у нас есть несколько каналов с 200+ подписчиков, поэтому пришлось искать обходные пути.

Плохие новости: идеально работающего решения нет. В интернете описано несколько способов обойти это ограничение, но на текущий момент они не работают — Telegram закрывает все лазейки.

Мы не смогли полностью автоматизировать работу с такими каналами, но сделали все возможное. Так в первый раз очистку от незарегистрированных пользователей придется провести вручную, сравнивая список подписчиков со списком из таблицы TG_ACTIVE_USERS, в которой хранятся данные о регистрациях. В дальнейшем мы рекомендуем администраторам не добавлять новых подписчиков руками или по открытым пригласительным ссылкам — только через заявки на вступление, одобряемые ботом. Автоматически работает удаление только уволенных сотрудников: скрипт находит в БД записи о пользователях, чьих номеров больше нет в LDAP-каталоге, и удаляет их из чата.

Продуктивизация

К боту также выдвигались требования по технической части в вопросах деплоя и отказоустойчивости, а именно простота развертывания новых версий и поддержание доступности приложения без участия разработчиков.

Для решения этих вопросов был использован CI\CD инструмент на базе GitLab — GitLab CI, для сборки Docker-образа и деплоя на целевую платформу исполнения приложения — корпоративный кластер Kubernetes. Для развертывания новой версии необходимо лишь запушить коммит с изменениями в коде приложения или манифесте и установить тег. Сборка образа реализована стандартным (для GitLab CI) методом — в контейнере DockerINDocker с последующей отправкой в репозиторий образов Artifactory. Для деплоя в инфраструктуру K8S используется стандартный инструмент — kubectl, запакованный в Docker-образ со всеми зависимостями.

Дашборд

На основании собранных данных мы разработали дашборд в Fine BI, позволяющий администраторам следить за развитием их каналов. С теми данными, которые собираем мы, можно визуализировать динамику количества участников по каждому чату и каналу, отслеживать присоединяющихся к чатам и выходящих из них сотрудников, выводить общую информацию по всем чатам, включая их администраторов. Используя указываемый при регистрации номер телефона, мы объединяем таблицу TG_CHATS_USERS с другими данными сотрудников и получаем возможность идентифицировать участников чатов, отслеживать использование чатов в разных подразделениях и департаментах.

Самые простые визуализации могут выглядеть, например, так:

А вот так выглядит детализированная информация о зарегистрировавшихся в боте сотрудниках:

Собираем бота по частям обратно и говорим о будущем

Конечно же, такой функционал был реализован не сразу. Мы постепенно тестировали, обновляли, дополняли нашего бота. А еще прошли 7 кругов ада с верификацией пользователей при первом подключении. Тогда нам пришлось долго объяснять и рассказывать о необходимости зарегистрироваться в боте, даже если ты уже являешься подписчиком чата, напоминать о сроках регистрации, а потом вручную удалять незарегистрированных и ловить волну недовольства.

Мы готовы и дальше развивать этот сервис и помогать другим сотрудникам использовать его функционал. Для успешного внедрения бота мы использовали корпоративную BPM-систему: пользователи могут создавать заявки на консультацию, исправление ошибок или доработку функционала. Эта практика оказалась полезной — мы не только помогли ряду сотрудников с подключением бота к их чатам, но и убедились, что сервис работает корректно, а также получили несколько идей для дальнейшего развития.

Что планируем реализовать в ближайшем будущем:

1) Переход на API. Хотим отказаться от специальных библиотек и обращаться напрямую к Telegram API/и Telegram Bot API

2) Дополнительные возможности бота: мониторинг неудачных регистраций, рассылка важной информации администраторам чатов в почту.

Делитесь в комментариях, внедряли ли вы бота авторизаций в своих каналах и чатах или планируете это делать? И какие нетривиальные функции вы решаете с его помощью?

© Habrahabr.ru