# List of Changes⚓︎

## 1.5.4⚓︎

Added:

- The `Message.forwarded_message` property — the original of a forwarded message

- The `max_size` parameter in `URLInputFile.read()` — aborts the download with `FileSizeTooLargeError` when the content exceeds the limit

Fixed:

- Parsing of forwarded messages (type `201`): `ForwardMessage` inherits from `Message` and gains all its parameters — `text`, `voice`, `document`, `reply_message`, `bind` and others; nested forwards are resolved recursively. A forwarded voice message no longer drops the whole update with `InvalidFieldValue`

- `getChatHistory`: the `fromMessageId` parameter is no longer sent as `null` — it caused the `399 WRONG_PAYLOAD_FORMAT` server error

- `URLInputFile`: the file size is now computed from the actually downloaded body. Sources that return a new file per request (e.g. camera snapshots) led to `400 Bad Request`: the size was taken from the headers of one response while the body of another was uploaded

- `URLInputFile`: redirecting URLs and servers rejecting HEAD requests are handled correctly; an error response (e.g. 404) is no longer treated as the file with the error-page size

Changed:

- `URLInputFile.prepare()` reads only HTTP headers and does not download the body; `Content-Length` is treated as an estimate. The exact size becomes known after the download and is the size declared to the server

- One `URLInputFile` object corresponds to one content: repeated sends and `clone()` reuse the downloaded bytes. Need a fresh file (e.g. a new camera frame) — create a new object

- `read(max_size=...)` aborts the download when the limit is exceeded; the `bot.max_file_size` limit now applies to URL files as well

- Metadata completeness (a non-empty name + size) is now guaranteed by the file classes themselves: `URLInputFile` resolves the name in `prepare()` (otherwise `FileUploadError`), `BufferedInputFile` and `FSInputFile` reject an empty `file_name` (`TypeError`/`ValueError`)

- `Message.box` is now optional — a forwarded message carries no `box`

## 1.5.3⚓︎

Fixed:

- Connect task cancellation in Python 3.10: an external cancellation (`task.cancel()`) now propagates to the caller

- The `httpx2` dependency is back to `>=2.7.0` (previously `>=2.13.0`)

- Tests are wired into GitHub Actions; CI updated: actions moved to Node 24, `setup-uv` pinned to v10.2.0, caching added

## 1.5.2⚓︎

Added:

- Python 3.14 support declared

Fixed:

- The version compatibility table in README

## 1.5.1⚓︎

Added:

- Version compatibility check: TrueConf Server 5.5.3–5.5.5 requires `python-trueconf-bot >=1.2.1,Fixed:

- The version compatibility table in README

## 1.5.0⚓︎

🚀 Major release! This is not only a set of new features, but also extensive work on stability.

Tip

Support for Python 3.10 ends on 31.10.2026, together with the end of its official support by the Python Software Foundation.

Added:

- Support for incoming voice messages with the `MessageType.VOICE_MESSAGE` (`205`) type

- Support for inline buttons via `InlineKeyboardMarkup`/`InlineKeyboardButton` (actions: command, URL, message, copy). Requires TrueConf Server 5.5.6 and TrueConf client apps for Windows, macOS and Linux version 8.6.0, TrueConf for Android 3.3.0, TrueConf for iOS 4.2.0

- Callback queries for handling button presses: the `@router.callback_query()` handler, `callback_query.edit_message(...)` and `callback_query.answer(...)` shortcuts

- Buttons with `wait_reply=True` and the `answerCommand` method temporarily raise `NotImplementedError`: the functionality is supported by TrueConf Server but awaits support from client applications. Once it becomes available, a new release will be published that removes this limitation

- Chat object: the `chat` field with the `Chat` model in `Message` and `LastMessage`

- Message replies: incoming reply messages now include `Message.reply_message` with the content of the original message being replied to

- System messages: the `SystemMessage` model and the `@router.system_message()` handler

- Reply with a quote via the `quote` parameter in `Message.reply()` and `Bot.send_message()`, as well as the `Message.quote` property

- Chat activity indicator: the `Bot.send_chat_activity()` method, the `ChatActivity` enum and the `ChatActivitySender.typing(...)` context manager

- In-memory file download size limit via the `max_in_memory_download_size` parameter

- The `LineBreak` node in `trueconf.utils.formatting` (`
` for HTML, `\n` for Markdown)

- The `message.location` and `message.contact` shortcuts for geolocation and contacts (vCard files and trueconf links)

- OAuth2 authentication via `Bot.from_oauth()` for servers with login/password authentication disabled. Requires TrueConf Server 5.5.3+

- New exceptions: `WSConnectionError`, `InMemoryDownloadLimitExceededError`, `FileUploadError`, `OAuthMissingScopeError`, `PasswordAuthDisabledError`

- Text descriptions for API error codes (399, 400–408) in `ApiError.message()`. Codes 400–408 relate to files and replace the single generic code 310 (“error while sending”) — now it is clear what exactly went wrong during the send

- The `caption_message_id` field in `SendFileResponse` — the ID of the caption message sent with a file; allows changing the file caption via `edit_message(...)`

- A custom `User-Agent` on all library requests in the format `python-trueconf-bot/ (Python/; /)`, e.g.: `python-trueconf-bot/1.5.0 (Python/3.12.4; Darwin/24.0.0)`

Changed:

- The `Underline` node in `trueconf.utils.formatting` now also renders in Markdown (`__text__`) — previously underline worked only in HTML markup

- File download: the `file_path` parameter sets the exact output path, parent directories are created automatically

- The `mimetype` parameter was renamed to `mime_type`

- `ws_max_retries`/`ws_max_delay` behavior: once the attempts are exhausted, the connection ends with `WSConnectionError`

- Bot shutdown now waits for running handlers and closes the WebSocket transport; a `timeout` parameter was added to `shutdown()`

- The HTTP client was migrated from `httpx` to `httpx2`

Fixed:

- Parsing of system messages in chat history and API responses

- File upload errors: the caller now receives `FileUploadError` with the original cause

- Infinite WebSocket reconnection after the retry limit is exhausted

- The WebSocket connection was not closed on bot shutdown — the session now properly closes the attached socket

- Download URLs and tokens no longer appear in logs in full: the query string is stripped from URLs (`https://server/.../files/download?token=...` → `https://server/.../files/download`), and tokens in debug logs are truncated to the last 30 characters

- Token acquisition in `Bot.from_credentials()` now respects the `https` and `web_port` parameters — previously the token was always requested via https:443, even if the server runs on http or a non-standard port

Deprecated:

- The `Message.chat_id` property — use `message.chat.chat_id` instead

- The `dest_path` parameter — use `file_path` instead (will be removed in version 2.0)

- The `mimetype` parameter — use `mime_type` instead

## 1.4.4⚓︎

Fixed:

- Fixed a library (bot) crash occurring when the LastMessage contained a notification about a chat avatar change #15.

## 1.4.3⚓︎

Fixed:

- Checking server version. Currently, the check is performed via the API first; if an error occurs, the check is based on the TrueConf service status.

## 1.4.2⚓︎

Fixed:

- Bot crash when server version field is empty

## 1.4.1⚓︎

Added:

- New parameter `timeout` in class `Bot` and `Bot.from_credentials()` method

Fixed:

- System events like `ChangedFileUploadLimits` don't have chat_id or author, which caused `DefaultKeyBuilder` to raise `RuntimeError`. Now `FSMMiddleware` checks for `chat_id/user_id` before building FSM context. System events pass through without FSM context.

Refactor:

- Improve network timeout logic for file download and upload:

- Remove hardcoded `chunk_size` from `httpx.stream` to prevent false ReadTimeout on slow networks.

- Configure `aiohttp.ClientTimeout` using `sock_read` instead of `total` to allow long file uploads without socket freezes.

- Enforce strict `int | float` types for timeouts, removing redundant `None` checks

- Update method docstrings to clearly reflect adaptive timeout behavior.

## 1.4.0⚓︎

Added:

- FSM (Finite State Machine) — a finite state machine mechanism. It allows you to implement step-by-step dialogs, such as questionnaires, forms, and setup wizards.
States are declared declaratively using `StatesGroup`/`State`, while data is stored in `FSMContext`. It supports nested groups, multiple storage strategies, and state-based filtering via `StateFilter`. Learn more: FSM.

- Middleware — a layer for processing events before and after handlers.
It allows you to log events, block them, check access, and modify data.
It supports two types: outer middleware, which runs before filters, and inner middleware, which runs after filters. Learn more: Middleware.

- The `skip_self_messages` parameter in `Bot()`. By default, it is set to `True`, so the bot automatically ignores messages sent by itself.
It can be disabled with `skip_self_messages=False`.

- Added `Message.reply_message`, containing the full message being replied to.

- Added the `SystemMessage` model for system Envelopes in live updates and chat history, together with the `@router.system_message()` handler.

Fixed:

- The history-clearing notification now preserves `for_all` as the server-provided `bool` value.

## 1.3.0⚓︎

Added:

- Added a health-check mechanism for tracking the bot connection state:

- push model via the `Bot(on_health_check=func_callback)` callback, which is called when the connection status changes;

- pull model via the `bot.health_check()` method, which returns the current bot state;

- `connected`, `authorized`, and `disconnected` statuses.

- Added `bot.me_id` support for storing the authorized bot identifier.

- Added the `message.mention` shortcut, which returns `True` if the current bot is mentioned in the message or if `@all` is used.

- Added the `trueconf.utils.formatting` module for convenient HTML/Markdown message construction with classes: `Text`, `Bold`, `Italic`, `Underline`, `Strikethrough`, `Link`, `Mention`, `AllMention`.

- Added the `truststore` dependency for working with the system trusted certificate store.

- Added the `SSLVerify` type for unified typing of the `verify_ssl` parameter: `bool | str | ssl.SSLContext`.

- Added the `bot.me_chat` property as the new name for getting the `chat_id` of the "Favorites" chat.

Changed:

- Updated the `verify_ssl` behavior:

- `verify_ssl=True` uses the system trusted certificate store through `truststore`;

- `verify_ssl=False` disables certificate verification;

- `verify_ssl="/path/to/ca.pem"` uses a custom CA bundle;

- `verify_ssl=ssl.SSLContext(...)` uses the provided SSL context.

- Updated the SSL logic for WebSocket connections: a single `self.ssl_context`, created via `build_ssl_context(...)`, is now used.

- Updated bot initialization logging: logs now include human-readable information about the SSL context.

Fixed:

- Fixed failures caused by incomplete certificate chains. Certificate chains can now be verified successfully by using the system trusted certificate store through `truststore` or by passing a custom SSL context.

Deprecated:

- The asynchronous `bot.me` property, which returns the `chat_id` of the "Favorites" chat, is now deprecated. Use `await bot.me_chat` instead.

Documentation:

- Added Context7 AI Assistant: interactive support for code and documentation.

- Added a new Sending messages documentation section covering:

- getting `chat_id`;

- sending text messages via `bot.send_message(...)`;

- replying with `reply_message_id`;

- forwarding messages via `bot.forward_message(...)`;

- text formatting via `trueconf.utils.formatting`;

- the 4096-character message length limit and using `safe_split_text(...)`.

- Added health-check documentation covering:

- push model via callback;

- pull model via `bot.health_check()`;

- an example of combined usage with an HTTP health endpoint.

- Added and updated docstrings for the formatting module, `Message.mention`, `verify_ssl`, and the health-check API.

- Added new sections: Shortcuts, Restrictions, Formatting, Exceptions.

## 1.2.3⚓︎

Added:

- Added a 10-second server response timeout. If no response is received within the timeout, an `asyncio.TimeoutError` is raised: `Request to {self.__api_method__} timed out after {timeout}s` (#12).

Fixed:

- Fixed cases where Mashumaro failed to parse a response, which could cause the application to crash (#8, #11).

## 1.2.2⚓︎

Fixed:

- Fixed a missing dependency: the `packaging` package, which is required to check the library version at bot startup.

## 1.2.1⚓︎

Added:

- Added support for TrueConf Server 5.5.4.

- Added the `receive_system_messages` flag to `Bot()` and `Bot.from_credentials()` to enable or disable receiving system messages.

- Added the new `bot.get_chat_participant()` method, which replaces `bot.has_chat_participant()`.

Fixed:

- Fixed support for TrueConf Server 5.5.3+. Removed an unnecessary version check that prevented the code from running with library version 1.2.0.

- Fixed documentation links to `llms.txt` and `llms-full.txt`.

Changed:

- When retrieving file information via `bot.get_file_info(file_id=...)`, the response now returns the `file_id` field instead of `info_hash`.

Deprecated:

- The `bot.has_chat_participant()` method has been deprecated. Use `bot.get_chat_participant()` instead.

## 1.2.0⚓︎

Added:

- Added support for TrueConf Server 5.5.3, including:

- chat title editing with `bot.edit_chat_title(...)`;

- chat avatar editing with `bot.edit_chat_avatar(...)`;

- chat history clearing with `bot.clear_chat_history(...)`;

- retrieving file storage limits with `bot.get_file_info_upload_limits(...)`;

- a new file transfer approach where the `file_name` parameter is now required for `FSInputFile(...)` and other file upload methods.

- Added caching for file storage limit settings. These settings are now used for pre-upload validation, and the library raises an exception if a file does not meet the configured constraints.

- Added `python-magic` and `filetype` libraries for more reliable file type detection based on magic numbers (byte signatures).

- Added automatic file extension appending when a filename does not contain an extension.

- Improved WebSocket connection stability with exponential backoff and a configurable retry strategy. You can control the maximum number of reconnection attempts with `ws_max_retries` and the maximum delay between attempts with `ws_max_delay` (#6).

- Added TrueConf Server version validation. The library now raises a `RuntimeError` with upgrade instructions if an incompatible server version is detected.

- Added the `safe_split_text` utility for safely splitting long messages exceeding 4096 characters into chunks of up to 4096 characters. This is especially useful for AI agents that generate long responses.

- Added AI-friendly documentation builds: `llms.txt` and `llms-full.txt`.

- Added and expanded logging.

Fixed:

- Fixed an issue with sending stickers in TrueConf Server 5.5.3+.

- Fixed issue #7.

- Fixed various minor bugs and made general improvements.

Deprecated:

- The `filename` and `mimetype` parameters are now deprecated.

- Please migrate to the new `snake_case` parameter naming, as the old parameters will be removed in future versions.

## 1.1.10⚓︎

Fixed:

- Fixed the missing `file_id` parameter in `SendFileResponse`.

## 1.1.9⚓︎

Added:

- Added TrueConf Server version validation. The library now raises a `RuntimeError` with update instructions if an incompatible server version is detected.

## 1.1.8⚓︎

Fixed:

- Added `verify_ssl` support for WSS connections. Previously, SSL verification was unconditionally bypassed when `https` was enabled; it is now correctly controlled by the configuration flag.

## 1.1.7⚓︎

Added:

- Added `reply_photo`, `reply_document`, and `reply_sticker` shortcut methods to the `Message` class.

- Added `reply_message_id` support to multiple methods and to the `SendFile` class.

Fixed:

- Fixed `quote_fields` being set to `False` in `aiohttp.FormData`.

- Set the default value of `last_message` to `None` in `GetChatByIdResponse` (fixes #4).

Deprecated:

- `reply_message` is now deprecated. Use `reply_message_id` instead.

## 1.1.6⚓︎

Refactored:

- Replaced local `verify_ssl` usage with `self.verify_ssl` in class methods.

## 1.1.5⚓︎

Fixed:

- Prevented `run()` from hanging when the connect task fails.

- Properly propagate `ApiErrorException` and other errors to the caller.

## 1.1.4⚓︎

Fixed:

- Removed the `chat_id` field from `RemoveChatResponse` (#1).

## 1.1.3⚓︎

Fixed:

- Fixed event propagation for multiple routers and subrouters.

## 1.1.2⚓︎

Added:

- Bumped the development status.

- Added `typing_extensions` to dependencies.

- Added and updated the downloads badge.

- Added imports for `Self` and `Unpack` from `typing_extensions`.

Fixed:

- Fixed `Message` shortcuts not working.

## 1.1.1⚓︎

Added:

- New classes for working with files: `FSInputFile`, `BufferedInputFile`, `URLInputFile`. More details can be found in the documentation.

- Support for displaying message history `display_history = True` when adding a user to a group chat or channel.

- Support for request and event for:

- role changes in a group chat or channel (request, notification);

- creation of the “Favorites” chat (request, notification).

- Ability to send files with a caption.

- Shortcut `.save_to_favorites()` for quickly saving a message to the "Favorites" chat.

- The asynchronous property `await bot.me`, which returns the `chat_id` of the "Saved Messages" chat.

Fixed:

- Stickers sent via `bot.send_sticker()` were displayed with a background due to an incorrect MIME type.

- The method `.remove_participant_from_chat()` did not work when an incomplete TrueConf ID was specified.

- Error unpacking the participant list due to an incorrect alias.

- Sometimes, when obtaining a token using `.from_credentials()`, a `400 Bad Requests` error would occur when using a digit password.

Modified:

- The `bot.server_name` property has become asynchronous. Use it as `await bot.server_name`.

## 1.0.0⚓︎

🎉 First Release!

- Stable version of the python-trueconf-bot library.

- Support for all major TrueConf ChatBot API methods.

- Aliases and keyboard shortcuts in the aiogram style (message.answer, message.reply, etc.).

- Asynchronous data transmission via the WebSocket protocol.

- Working with files (sending and uploading).

- Documentation: trueconf.github.io/python-trueconf-bot/

- PyPI: pypi.org/project/python-trueconf-bot/

October 12, 2026

November 12, 2025