Список изменений⚓︎

1.5.4⚓︎

Добавлено:

Свойство Message.forwarded_message — оригинал пересланного сообщения
Параметр max_size в URLInputFile.read() — обрывает загрузку с FileSizeTooLargeError, если содержимое превышает лимит

Исправлено:

Разбор пересланных сообщений (тип 201): ForwardMessage наследуется от Message и получает все его параметры — text, voice, document, reply_message, bind и другие; вложенные пересылки разворачиваются рекурсивно. Пересланное голосовое сообщение больше не «роняет» обновление с InvalidFieldValue
getChatHistory: параметр fromMessageId больше не отправляется как null — это вызывало ошибку сервера 399 WRONG_PAYLOAD_FORMAT
URLInputFile: размер файла вычисляется по фактически скачанному телу. Источники, отдающие новый файл на каждый запрос (например, снимки с камер), приводили к 400 Bad Request: размер определялся по заголовкам одного ответа, а отправлялось тело другого
URLInputFile: URL с редиректами и серверы, отвергающие HEAD-запросы, обрабатываются корректно; ответ с ошибкой (например, 404) больше не принимается за файл с размером error-страницы

Изменено:

URLInputFile.prepare() читает только HTTP-заголовки и не скачивает тело; Content-Length считается оценкой. Точный размер становится известен после скачивания, и именно он передаётся серверу
Один объект URLInputFile соответствует одному содержимому: повторные отправки и clone() используют уже скачанные байты. Нужен свежий файл (например, новый кадр камеры) — создайте новый объект
read(max_size=...) обрывает загрузку при превышении лимита; лимит bot.max_file_size теперь применяется и к URL-файлам
Гарантия полноты метаданных (непустое имя + размер) перенесена в сами классы файлов: URLInputFile разрешает имя в prepare() (иначе FileUploadError), BufferedInputFile и FSInputFile отклоняют пустое file_name (TypeError/ValueError)
Message.box стал опциональным — у пересланного сообщения нет box

1.5.3⚓︎

Исправлено:

Отмена задачи подключения в Python 3.10: внешняя отмена (task.cancel()) теперь корректно пробрасывается вызывающему коду
Зависимость httpx2 возвращена к >=2.7.0 (было >=2.13.0)
Тесты подключены к GitHub Actions; обновлён CI: действия переведены на Node 24, setup-uv зафиксирован на v10.2.0, добавлен кэш

1.5.2⚓︎

Добавлено:

Объявлена поддержка Python 3.14

1.5.1⚓︎

Добавлено:

Проверка совместимости версий: TrueConf Server 5.5.3–5.5.5 требует python-trueconf-bot >=1.2.1,<1.5.0 (с подсказкой по установке)

Исправлено:

Таблица совместимости версий в README

1.5.0⚓︎

🚀 Крупное обновление! Это не только набор новых возможностей, но и масштабная работа над стабильностью.

Tip

Поддержка Python 3.10 прекращается 31.10.2026 — вместе с окончанием её официальной поддержки Python Software Foundation.

Добавлено:

Поддержка входящих голосовых сообщений с типом MessageType.VOICE_MESSAGE (205)
Поддержка инлайн-кнопок через InlineKeyboardMarkup/InlineKeyboardButton (действия: команда, URL, сообщение, копирование). Требуется TrueConf Server 5.5.6 и клиентские приложения TrueConf для Windows, macOS и Linux версии 8.6.0, TrueConf для Android 3.3.0, TrueConf для iOS 4.2.0
Callback-запросы для обработки нажатий на кнопки: обработчик @router.callback_query(), шорткаты callback_query.edit_message(...) и callback_query.answer(...)
Кнопки с wait_reply=True и метод answerCommand временно вызывают NotImplementedError: функциональность поддерживается сервером TrueConf, но ожидает поддержки со стороны клиентских приложений. После её появления будет выпущен новый релиз, снимающий это ограничение
Объект чата: поле chat с моделью Chat в Message и LastMessage
Ответы на сообщения: во входящем сообщении-ответе появился Message.reply_message с содержимым исходного сообщения, на которое дан ответ
Системные сообщения: модель SystemMessage и обработчик @router.system_message()
Ответ с цитатой через параметр quote в Message.reply() и Bot.send_message(), а также свойство Message.quote
Индикатор активности в чате: метод Bot.send_chat_activity(), перечисление ChatActivity и контекстный менеджер ChatActivitySender.typing(...)
Ограничение размера файла, загружаемого в память, параметром max_in_memory_download_size
Узел LineBreak в trueconf.utils.formatting (<br> для HTML, \n для Markdown)
Шорткаты message.location для геолокации и message.contact для контактов (vCard-файлы и trueconf-ссылки)
Авторизация через OAuth2 с помощью Bot.from_oauth() для серверов с отключённой поддержкой авторизации через логин и пароль. Требуется TrueConf Server 5.5.3+
Новые исключения: WSConnectionError, InMemoryDownloadLimitExceededError, FileUploadError, OAuthMissingScopeError, PasswordAuthDisabledError
Текстовые расшифровки кодов ошибок API (399, 400–408) в ApiError.message(). Коды 400–408 относятся к файлам и заменяют один общий код 310 («ошибка при отправке») — теперь понятно, что именно пошло не так при отправке
Поле caption_message_id в SendFileResponse — ID сообщения с подписью, отправленного вместе с файлом; позволяет изменить подпись файла через edit_message(...)
Кастомный User-Agent во всех запросах библиотеки в формате python-trueconf-bot/<version> (Python/<version>; <OS>/<release>), например: python-trueconf-bot/1.5.0 (Python/3.12.4; Darwin/24.0.0)

Изменено:

Узел Underline в trueconf.utils.formatting теперь рендерится и в Markdown (__текст__) — ранее подчёркивание работало только в HTML-разметке
Скачивание файлов: параметр file_path задаёт точный путь, родительские каталоги создаются автоматически
Параметр mimetype переименован в mime_type
Поведение ws_max_retries/ws_max_delay: после исчерпания попыток подключение завершается с WSConnectionError
Завершение бота ожидает запущенные обработчики и закрывает WebSocket-транспорт; в shutdown() добавлен параметр timeout
HTTP-клиент переведён с httpx на httpx2

Исправлено:

Разбор системных сообщений в истории чата и ответах API
Ошибки загрузки файлов: вызывающий код получает FileUploadError с исходной причиной
Бесконечное переподключение WebSocket после исчерпания лимита попыток
При остановке бота WebSocket-соединение не закрывалось — теперь сессия корректно закрывает подключённый сокет
URL скачивания и токены больше не попадают в лог целиком: у URL удаляется query-строка (https://server/.../files/download?token=... → https://server/.../files/download), а токен в debug-логах обрезается до последних 30 символов
Получение токена в Bot.from_credentials() теперь учитывает параметры https и web_port — ранее токен запрашивался по https:443, даже если сервер работает по http или на нестандартном порту

Устарело:

Свойство Message.chat_id — используйте message.chat.chat_id
Параметр dest_path — используйте file_path (удаление в версии 2.0)
Параметр mimetype — используйте mime_type

1.4.4⚓︎

Исправлено:

Исправлено падение библиотеки (бота), возникавшее, когда LastMessage содержал уведомление об изменении аватара чата (#15).

1.4.3⚓︎

Исправлено:

Исправлена проверка версии сервера. Теперь проверка выполняется сначала через API, а в случае ошибки — на основе статуса службы TrueConf.

1.4.2⚓︎

Исправлено:

Исправлено падение бота при пустом поле версии сервера.

1.4.1⚓︎

Добавлено:

Добавлен новый параметр timeout в класс Bot и метод Bot.from_credentials().

Исправлено:

Системные события (например, ChangedFileUploadLimits) не содержат chat_id или author, из-за чего DefaultKeyBuilder вызывал RuntimeError. Теперь FSMMiddleware проверяет наличие chat_id/user_id перед построением FSM-контекста. Системные события проходят без FSM-контекста.

Рефакторинг:

Улучшена логика таймаутов для загрузки и скачивания файлов:
- убран жёстко заданный chunk_size из httpx.stream для предотвращения ложного ReadTimeout на медленных сетях;
- aiohttp.ClientTimeout настраивается через sock_read вместо total, чтобы длительные загрузки файлов не замирали;
- строгие типы int | float для таймаутов, убраны лишние проверки None;
- обновлены docstring методов, отражающие адаптивное поведение таймаутов.

1.4.0⚓︎

Добавлено:

FSM (Finite State Machine) — механизм конечных автоматов состояний. Позволяет реализовать пошаговые диалоги: анкеты, формы, мастер-настройки. Состояния объявляются декларативно через StatesGroup/State, данные хранятся в FSMContext. Поддерживает вложенные группы, несколько стратегий хранения и фильтрацию по состоянию через StateFilter. Подробнее: FSM.
Middleware — прослойка для обработки событий до и после хендлеров. Позволяет логировать, блокировать, проверять доступ и модифицировать данные. Поддерживает два типа: outer (до фильтров) и inner (после фильтров). Подробнее: Middleware.
Параметр skip_self_messages в Bot(). По умолчанию True — бот автоматически игнорирует сообщения, отправленные самим собой. Отключается параметром skip_self_messages=False.
Поле Message.reply_message с полным сообщением, на которое был отправлен ответ.
Модель SystemMessage для системных Envelope в live-потоке и истории чата, а также обработчик @router.system_message().

Исправлено:

Поле for_all нотификации очистки истории теперь сохраняет серверный тип bool.

1.3.0⚓︎

Добавлено:

Механизм health-check для отслеживания состояния подключения бота:
- push-модель через callback Bot(on_health_check=func_callback), который вызывается при изменении статуса подключения;
- pull-модель через метод bot.health_check(), который возвращает текущее состояние бота.
- статусы connected, authorized и disconnected.
Поддержка bot.me_id для хранения идентификатора авторизованного бота.
Шорткат message.mention, который возвращает True, если в сообщении упомянут текущий бот или используется @all.
Модуль форматирования trueconf.utils.formatting для удобного построения HTML/Markdown-сообщений через классы: Text, Bold, Italic, Underline, Strikethrough, Link, Mention, AllMention.
Зависимость truststore для работы с системным хранилищем доверенных сертификатов.
Тип SSLVerify для унифицированной типизации параметра verify_ssl: bool | str | ssl.SSLContext.
Свойство bot.me_chat как новое имя для получения chat_id чата "Избранное".

Изменено:

Обновлена логика работы verify_ssl:
- verify_ssl=True использует системное хранилище доверенных сертификатов через truststore;
- verify_ssl=False отключает проверку сертификата;
- verify_ssl="/path/to/ca.pem" использует пользовательский CA bundle;
- verify_ssl=ssl.SSLContext(...) использует переданный SSL-контекст.
Обновлена SSL-логика для WebSocket-подключений: теперь используется единый self.ssl_context, созданный через build_ssl_context(...).
Обновлено логирование при инициализации бота: теперь в лог выводится человекочитаемая информация о SSL-контексте.

Исправлено:

Обработка неполной цепочки сертификатов заканчивалась неудачей. Теперь цепочка сертификатов проверяется успешно за счёт возможности использовать системное хранилище через truststore или передавать собственный SSL-контекст.

Устарело:

Асинхронное свойство bot.me, которое возвращает chat_id чата "Избранное", помечено как устаревшее. Используйте await bot.me_chat вместо него.

Документация:

Интегрирован ИИ-ассистент (виджет чата Context7): интерактивный помощник для консультаций по коду и документации.
Добавлен новый раздел документации Отправка сообщений с описанием:
- получения chat_id;
- отправки текстовых сообщений через bot.send_message(...);
- отправки ответа через reply_message_id;
- пересылки сообщений через bot.forward_message(...);
- форматирования текста через trueconf.utils.formatting;
- ограничения длины сообщения в 4096 символов и использования safe_split_text(...).
Добавлено описание health-check в документацию:
- push-модель через callback;
- pull-модель через bot.health_check();
- пример совместного использования с HTTP health endpoint.
Добавлены и обновлены docstring для модуля форматирования, Message.mention, verify_ssl и health-check API.
Добавлены новые разделы: Шорткаты, Ограничения, Formatting, Exceptions.

1.2.3⚓︎

Добавлено:

Добавлен таймаут ожидания ответа сервера — 10 секунд. Если ответ не будет получен за это время, будет вызвано исключение asyncio.TimeoutError: Request to {self.__api_method__} timed out after {timeout}s (#12).

Исправлено:

Исправлены ситуации, когда Mashumaro не мог распарсить ответ, из-за чего приложение могло завершиться с ошибкой (#8, #11).

1.2.2⚓︎

Исправлено:

Исправлена отсутствующая зависимость: пакет packaging, необходимый для проверки версии библиотеки при запуске бота.

1.2.1⚓︎

Добавлено:

Добавлена поддержка TrueConf Server 5.5.4.
Добавлен флаг receive_system_messages в Bot() и Bot.from_credentials() для включения или отключения получения системных сообщений.
Добавлен новый метод bot.get_chat_participant(), который заменяет bot.has_chat_participant().

Исправлено:

Исправлена поддержка TrueConf Server 5.5.3+. Удалена лишняя проверка версии, из-за которой код не запускался при использовании версии библиотеки 1.2.0.
Исправлены ссылки в документации на llms.txt и llms-full.txt.

Изменено:

При получении информации о файле через bot.get_file_info(file_id=...) ответ теперь возвращает поле file_id вместо info_hash.

Устарело:

Метод bot.has_chat_participant() помечен как устаревший. Используйте bot.get_chat_participant() вместо него.

1.2.0⚓︎

Добавлено:

Добавлена поддержка TrueConf Server 5.5.3, включая:
- изменение названия чата с помощью bot.edit_chat_title(...);
- изменение аватара чата с помощью bot.edit_chat_avatar(...);
- очистку истории чата с помощью bot.clear_chat_history(...);
- получение лимитов файлового хранилища с помощью bot.get_file_info_upload_limits(...);
- новый подход к передаче файлов, при котором параметр file_name теперь обязателен для FSInputFile(...) и других методов загрузки файлов.
Добавлено кэширование настроек лимитов файлового хранилища. Эти настройки теперь используются для предварительной проверки перед загрузкой, и библиотека вызывает исключение, если файл не соответствует заданным ограничениям.
Добавлены библиотеки python-magic и filetype для более надежного определения типа файла по magic numbers (байтовым сигнатурам).
Добавлено автоматическое добавление расширения файла, если оно отсутствует в имени файла.
Улучшена стабильность WebSocket-соединения: добавлены экспоненциальная задержка и настраиваемая стратегия повторных подключений. Теперь можно управлять максимальным количеством попыток повторного подключения через ws_max_retries и максимальной задержкой между попытками через ws_max_delay (#6).
Добавлена проверка версии TrueConf Server. Теперь библиотека вызывает RuntimeError с инструкциями по обновлению, если обнаружена несовместимая версия сервера.
Добавлена утилита safe_split_text для безопасного разделения длинных сообщений, превышающих 4096 символов, на части длиной до 4096 символов. Это особенно полезно для ИИ-агентов, которые генерируют длинные ответы.
Добавлены сборки документации, удобные для ИИ: llms.txt и llms-full.txt.
Добавлено и расширено логирование.

Исправлено:

Исправлена проблема с отправкой стикеров в TrueConf Server 5.5.3+.
Исправлена проблема #7.
Исправлены различные мелкие ошибки и внесены общие улучшения.

Устарело:

Параметры filename и mimetype теперь помечены как устаревшие.
Перейдите на новые имена параметров в формате snake_case, так как старые параметры будут удалены в будущих версиях.

1.1.10⚓︎

Исправлено:

Исправлено отсутствие параметра file_id в SendFileResponse.

1.1.9⚓︎

Добавлено:

Добавлена проверка версии TrueConf Server. Теперь библиотека вызывает RuntimeError с инструкциями по обновлению, если обнаружена несовместимая версия сервера.

1.1.8⚓︎

Исправлено:

Добавлена поддержка verify_ssl для WSS-соединений. Ранее проверка SSL безусловно отключалась при включенном https; теперь она корректно управляется флагом конфигурации.

1.1.7⚓︎

Добавлено:

Добавлены шорткаты reply_photo, reply_document и reply_sticker в класс Message.
Добавлена поддержка reply_message_id в нескольких методах и в классе SendFile.

Исправлено:

Исправлено значение quote_fields=False в aiohttp.FormData.
Установлено значение по умолчанию None для last_message в GetChatByIdResponse (исправляет #4).

Устарело:

reply_message теперь помечен как устаревший. Используйте reply_message_id вместо него.

1.1.6⚓︎

Рефакторинг:

Локальное использование verify_ssl заменено на self.verify_ssl в методах класса.

1.1.5⚓︎

Исправлено:

Предотвращено зависание run(), если задача подключения завершается с ошибкой.
ApiErrorException и другие ошибки теперь корректно передаются вызывающему коду.

1.1.4⚓︎

Исправлено:

Удалено поле chat_id из RemoveChatResponse (#1).

1.1.3⚓︎

Исправлено:

Исправлено распространение событий для нескольких роутеров и подроутеров.

1.1.2⚓︎

Добавлено:

Обновлен статус разработки.
Добавлен typing_extensions в зависимости.
Добавлен и обновлен бейдж загрузок.
Добавлены импорты Self и Unpack из typing_extensions.

Исправлено:

Исправлена неработающая функциональность шорткатов Message.

1.1.1⚓︎

Добавлено:

Новые классы для работы с файлами: FSInputFile, BufferedInputFile, URLInputFile. Подробнее — в документации.
Поддержка отображения истории сообщений display_history = True при добавлении пользователя в групповой чат или канал.
Поддержка запроса и события для:
- изменения роли в групповом чате или канале (запрос, уведомление);
- создания чата “Избранное” (запрос, уведомление).
Возможность отправки файлов с подписью (caption).
Шорткат .save_to_favorites() для быстрого сохранения сообщения в чат "Избранное".
Асинхронное свойство await bot.me, возвращающее chat_id чата "Избранное".

Исправлено:

Стикеры, отправленные через bot.send_sticker(), отображались с фоном из-за некорректного MIME-типа.
Метод .remove_participant_from_chat() не работал при указании неполного TrueConf ID.
Ошибка при распаковке списка участников из-за некорректного алиаса.
Иногда при получении токена с помощью .from_credentials() возникала ошибка 400 Bad Requests при использовании цифрового (digit) пароля.

Изменено:

Свойство bot.server_name стало асинхронным. Используйте его как await bot.server_name.

1.0.0⚓︎

🎉 Первый релиз!

Стабильная версия библиотеки python-trueconf-bot.
Поддержка всех основных методов API TrueConf ChatBot.
Псевдонимы и сочетания клавиш в стиле aiogram (message.answer, message.reply и т. д.).
Асинхронная передача данных по протоколу WebSocket.
Работа с файлами (отправка и загрузка).
Документация: trueconf.github.io/python-trueconf-bot/
PyPI: pypi.org/project/python-trueconf-bot/