База знаний Автоматизация и API

Как управлять TrueConf Server с помощью его API и бота Telegram

Антон Бааджи

23 февраля 2022

7 мин.

Администратор TrueConf Server может получать быстрый доступ к важной информации сервера, используя для этого популярные мессенджеры, например, Telegram. Для этого можно создать бота, который с помощью TrueConf Server API будет получать необходимые данные. Разместить бота можно как на своём сервере локально, так и на специализированном сервисе для онлайн-разработки.

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

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

Далее по тексту ошибочно запущенные конференции для краткости названы «забытыми», то есть их забыли остановить владелец и ведущие. Например, проводился вебинар, гости покинули его, а ведущий свернул клиентское приложение, не остановив мероприятие. Оно продолжает идти, а если была включена запись – то и зря занимать место на SSD или HDD разрастающимся файлом записи.

Для примера “забытой” мы считаем такую конференцию:

она длится дольше одного часа;
в ней остался один только владелец или ведущий;
в ней есть участники, но среди них нет ни одного ведущего.

Необходимые условия для запуска

Для успешного запуска бота требуется выполнение двух условий:

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

Внимание!

Представленный код является ознакомительным примером. Безопасность бота обеспечивается на уровне протокола OAuth 2.0, сервиса Telegram путём заявленного на его стороне шифрования данных, а также на стороне настроек сети (правила доступа, брандмауэр и т.п.). Т.к. через интерфейс бота передаются только сигналы от кнопок виртуальной клавиатуры, то через него нельзя будет послать какие-либо несанкционированные команды или исполняемый код.

Регистрация своего бота и его настройка

Для использования Telegram-бота вам понадобится официальный бот BotFather.

BotFather – это единственный бот, который управляет ботами в Telegram. Подробнее читайте в официальной документации.

Чтобы создать бота:

Откройте BotFather и нажмите Запустить или Старт.
У вас откроется список возможностей бота. Вам понадобится команда /newbot. Нажмите на неё в списке, или отправьте боту новое сообщение /newbot.
В дальнейшем список доступных команд можно открыть с помощью кнопок (мобильная версия), (десктопная версия) или просто набрав / в поле ввода сообщения в чате с BotFather.
Далее BotFather предложит назвать нового бота. Придумайте название, например TCS [name_org, где [name_org] — название вашей организации.
Теперь придумайте имя пользователя (username) для вашего бота. В имени обязательно должно присутствовать слово bot, это требование Telegram, например, tcs_[name_org]_bot.
Обратите внимание, что название бота и его имя пользователя – это публичные имена, по которым его можно найти через глобальный поиск.
В ответ вы получите сообщение со сведениями о созданном боте и токеном доступа к нему с помощью HTTP API в виде:
5032177032:AAGahjzZ6zbWSEsVFj13Ki-YMPhPEPzQjxE

Нажмите на токен в тексте сообщения, чтобы скопировать его в буфер обмена. После чего сохраните его в надёжном месте – он понадобится вам в дальнейшем для использования бота.

Для того чтобы перейти в настройки вашего бота, выполните команду /mybots и выберите соответствующее имя пользователя. У вас откроется меню, в котором можно:

аннулировать текущий токен, при этом новый токен создаётся автоматически;
редактировать имя, приветственное сообщение, описание, изображение;
добавить команды.

Теперь, когда бот настроен, можно перейти к его запуску.

Подготовка файла SETTINGS

Предварительно вам понадобится подготовить файл настроек с данными для доступа к своему боту и параметрами серверов.

На вашей рабочей машине создайте файл в формате JSON, например, settings.json. Откройте в любом текстовом редакторе и вставьте в него этот текст:

{
    "tg-api-token": "",
    "tg-users-id": [],
    "servers": {
        "server-name": {
            "ip": "",
            "client_id": "",
            "client_secret": "",
            "access_token": "",
            "server_status": {
                "state": 0,
                "timeout": 15
            },
            "ssl_certificate": ""
        }
    }
}

{

"tg-api-token": "",

"tg-users-id": [],

"servers": {

"server-name": {

"ip": "",

"client_id": "",

"client_secret": "",

"access_token": "",

"server_status": {

"state": 0,

"timeout": 15

"ssl_certificate": ""

}

Теперь вам нужно правильно заполнить эту структуру данных.

tg-api-token — токен доступа HTTP API Telegram.

tg-users-id — ваш числовой Telegram ID. Telegram обеспечивает безопасность доступа к боту с помощью уникальных ID пользователей, поэтому чтобы вы могли получить ответ от бота, вам понадобится узнать свой Telegram ID. Чтобы получить его, пришлите боту @userinfobot любое сообщение.

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

servers — словарь, который содержит информацию о ваших серверах.

Замените server-name на ваше имя сервера, т.к. это имя будет отображаться в названии кнопок.

ip — IP-адрес сервера, или доменное имя.

client_id, client_secret будут доступны вам после создания OAuth2 приложения. О том, как его создать, читайте в нашей документации.

Для нашего примера вам понадобится отметить такие разрешения в OAuth приложении:

conferences;
users:read;
logs.calls:read;
logs.calls.participants:read.

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

timeout — это время в секундах, через которое бот будет проверять статус сервера (Работает, Отключен). По умолчанию указано 15 секунд, но вы можете ввести своё значение.

ssl_certificate — если этот параметр true (чувствительно к регистру), то каждый запрос сервера будет проходить проверку SSL сертификата. Если ваш сервер использует самоподписанный сертификат, то в этом параметре в кавычках укажите путь к нему (используйте прямой слеш /). Если код используется на доверенной машине (например, находящейся в вашей корпоративной сети и доступ к ней только у вас), то напишите false – это отключит проверку сертификата. Если в кавычках не указан путь, то это также приравнивается к false.

После заполнения файла у вас должна получится структура как на примере ниже.

{
    "tg-api-token": "5032177032:AAGahjzZ6zbWSEsVFj13Ki-YMPhPEPzQjxE",
    "tg-users-id": [123456789,123456789,123456789],
    "servers": {
        "192.168.0.1": {
            "ip": "192.168.0.1",
            "client_id": "e2633da5cfbc56f43f69c30f06727dfe4fa1a067",
            "client_secret": "b97fc03b30d8f3011dc13abd205ec9f5610861e0",
            "access_token": "2f7d2b5eeba33fcfbe7c2f419b0d2114dbe5dc27",
            "server_status": {
                "state": 0,
                "timeout": 15
            },
            "ssl_certificate": true
        },
        "server #2": {
            "ip": "192.168.0.2",
            "client_id": "e2633da5cfbc56f43f69c30f06727dfe4fa1a067",
            "client_secret": "b97fc03b30d8f3011dc13abd205ec9f5610861e0",
            "access_token": "2f7d2b5eeba33fcfbe7c2f419b0d2114dbe5dc27",
            "server_status": {
                "state": 0,
                "timeout": 15
            },
            "ssl_certificate": false
        },
        "Сервер 3": {
            "ip": "192.168.0.3",
            "client_id": "e2633da5cfbc56f43f69c30f06727dfe4fa1a067",
            "client_secret": "b97fc03b30d8f3011dc13abd205ec9f5610861e0",
            "access_token": "2f7d2b5eeba33fcfbe7c2f419b0d2114dbe5dc27",
            "server_status": {
                "state": 0,
                "timeout": 15
            },
            "ssl_certificate": "C:/certificates/ca.crt"
        }
    }
}

{

"tg-api-token": "5032177032:AAGahjzZ6zbWSEsVFj13Ki-YMPhPEPzQjxE",

"tg-users-id": [123456789,123456789,123456789],

"servers": {

"192.168.0.1": {

"ip": "192.168.0.1",

"client_id": "e2633da5cfbc56f43f69c30f06727dfe4fa1a067",

"client_secret": "b97fc03b30d8f3011dc13abd205ec9f5610861e0",

"access_token": "2f7d2b5eeba33fcfbe7c2f419b0d2114dbe5dc27",

"server_status": {

"state": 0,

"timeout": 15

"ssl_certificate": true

"server #2": {

"ip": "192.168.0.2",

"client_id": "e2633da5cfbc56f43f69c30f06727dfe4fa1a067",

"client_secret": "b97fc03b30d8f3011dc13abd205ec9f5610861e0",

"access_token": "2f7d2b5eeba33fcfbe7c2f419b0d2114dbe5dc27",

"server_status": {

"state": 0,

"timeout": 15

"ssl_certificate": false

"Сервер 3": {

"ip": "192.168.0.3",

"client_id": "e2633da5cfbc56f43f69c30f06727dfe4fa1a067",

"client_secret": "b97fc03b30d8f3011dc13abd205ec9f5610861e0",

"access_token": "2f7d2b5eeba33fcfbe7c2f419b0d2114dbe5dc27",

"server_status": {

"state": 0,

"timeout": 15

"ssl_certificate": "C:/certificates/ca.crt"

}

Как запустить бота локально

Чтобы запустить бота на локальной машине, нужно установить Python, настроить виртуальное окружение и установить в него все недостающие зависимости (библиотеки).

Если вы используете операционную систему Windows, вам нужно установить Python. В ОС Linux Python установлен по умолчанию, в терминале выполните команду python --version чтобы проверить это.

Установка Python на Windows

Перейдите на официальный сайт python.org, в меню выберите пункт Downloads и под строкой Download for Windows нажмите кнопку Python x.x.x, где x.x.x — текущая релизная версия Python.

Откройте скачанный установочный файл, отметьте флажок Add Python x.x to PATH и нажмите Install Now.

Загрузка репозитория

Чтобы скопировать репозиторий к себе на компьютер, откройте его страницу, нажмите кнопку Code → Download ZIP, и распакуйте загруженный архив.

Запуск с использованием Poetry

Для запуска бота на локальной машине мы советуем вам использовать Poetry.

Poetry — это инструмент для управления зависимостями в Python.

Для начала вам нужно установить Poetry, для этого откройте PowerShell и выполните команду:

(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py -UseBasicParsing).Content | python -

1	(Invoke-WebRequest -Uri https://raw.githubusercontent.com/python-poetry/poetry/master/install-poetry.py -UseBasicParsing).Content \| python -

Для корректной работы Poetry перезапустите PowerShell.

Теперь в PowerShell перейдите в папку с ранее распакованными файлами, и выполните команду poetry install. После установки необходимых зависимостей выполните команду poetry run python main.py.

При успешном запуске бота в терминале отобразится надпись Bot is running…

Использование облачных сервисов

Прежде чем перейти к запуску бота в облачном сервисе, нужно клонировать наш репозиторий GitHub. Поэтому вам понадобится учетная запись на GitHub, чтобы создать аккаунт, нажмите кнопку Sing up в правом верхнем углу.

Если у вас уже аккаунт, нажмите кнопку Fork на странице нашего репозитория. После этого у вас откроется скопированный репозиторий в вашем аккаунте.

Replit

Регистрация

Replit — это веб-сервис, где можно писать и запускать код прямо в браузере, ничего не устанавливая к себе на компьютер.

Чтобы пользоваться сервисом вам понадобиться создать аккаунт. Для этого в правом верхнем углу нажмите на кнопку Sing up, введите логин, email и пароль или войдите с помощью популярного сервиса:

Импортирование проекта с GitHub

Нажмите кнопку Create.
В открывшимся окне нажмите Import from GitHub.
В выпадающем списке GitHub URL выберите нужный репозиторий.
Нажмите кнопку Import from Github.

Начнется процесс импорта репозитория:

По завершении процесса, у вас откроется окно с данной инструкцией по использованию бота.

Далее в левом меню нажмите кнопку , в поле key введите settings, в поле value вставьте содержимое ранее подготовленного файла settings.json и нажмите кнопку Add new secret.

Мы настоятельно не рекомендуем загружать в Replit ваши сертификаты, так как это небезопасно. Перед добавлением содержимого из settings.json, убедитесь что параметр ssl_certificate правильно отредактирован.

Редактирование файла main.py

В меню слева откройте файл main.py и в функции def get_access_token закомментируйте строки:

with open("settings.json", "w") as read_file:
    json.dump(SETTINGS, read_file) # for local file

1 2	with open("settings.json", "w") as read_file: json.dump(SETTINGS, read_file) # for local file

и раскомментируйте строку:

# os.environ['settings'] = json.dumps(SETTINGS) # for Replit

1	# os.environ['settings'] = json.dumps(SETTINGS) # for Replit

Аналогично в конце файла в блоке if __name__ == '__main__' закомментируйте строки:

with open("settings.json", "r") as read_file:
    SETTINGS = json.load(read_file)

1 2	with open("settings.json", "r") as read_file: SETTINGS = json.load(read_file)

и раскомментируйте строку:

# SETTINGS = json.loads(os.environ['settings']) # for Replit

1	# SETTINGS = json.loads(os.environ['settings']) # for Replit

Запуск бота на сервисе

Чтобы активировать исполнение кода бота, нажмите кнопку Run в верхней части страницы. Если вы всё верно настроили, то в правой части окна в панели вывода отобразится строка Bot is running....

Непрерывное выполнение кода

По умолчанию любой проект в бесплатном аккаунте на Replit «засыпает» через определенное время, на практике было получено значение в один час. Чтобы изменить это поведение, вам нужно оформить подписку на платный тариф Hacker. Для этого выполните:

Войдите в ваш аккаунт и нажмите кнопку Upgrade.
Нажмите кнопку Upgrade to Hacker.
Оплатите подписку с помощью платежной системы Stripe. Заполните все необходимые поля и нажмите кнопку Подписаться.

Далее откройте ваш проект и нажмите по его названию в верхнем левом углу. В нижней части появившегося окна переведите переключатель Always On в активное положение. Теперь ваш бот будет работать до тех пор, пока вы не остановите его сами вручную.

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

Предыдущая статья Следующая статья

Рубрики

Как управлять TrueConf Server с помощью его API и бота Telegram

Необходимые условия для запуска

Регистрация своего бота и его настройка

Подготовка файла SETTINGS

Как запустить бота локально

Установка Python на Windows

Загрузка репозитория

Запуск с использованием Poetry

Использование облачных сервисов

Replit

Регистрация

Импортирование проекта с GitHub

Редактирование файла main.py

Запуск бота на сервисе

Непрерывное выполнение кода

Попробуйте безопасную ВКС-платформу Труконф!

Крупнейшее ВКС-сообщество в России

Актуальные новости из мира ВКС