python-trueconf-bot

https://trueconf.github.io/python-trueconf-bot
Admin
Python TrueConf Bot is an asynchronous library for creating and managing chatbots on the TrueConf...
Tokens:109,005
Snippets:1,417
Trust Score:9.7
Update:3 months ago
Show doc for...
Tokens:
Raw
### Dynamic Router Example

Source: https://trueconf.github.io/python-trueconf-bot/latest/llms-full.txt

Shows the beginning of an example for creating a dynamic router using `Router` and `F` from the `trueconf` library.

```python
from trueconf import Router, F
r = Router()

```

--------------------------------

### Example Usage of URLInputFile

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Types?q=

Example of how to create a URLInputFile and send it as a document using the bot. The file is downloaded from the provided URL.

```python
file = URLInputFile("https://example.com/file.pdf")
await bot.send_document(chat_id="...", file=file)
```

--------------------------------

### FSInputFile Example

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Types

Example demonstrating how to use FSInputFile to send a document via the bot.

```APIDOC
### Example

```python
file = FSInputFile("example.pdf")
await bot.send_document(chat_id="...", file=file)
```
```

--------------------------------

### start

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Bot?q=

Starts the bot by connecting to the server and listening for incoming events. This method is safe to call multiple times; subsequent calls are ignored if the connection is already active.

```APIDOC
## start `async`

### Description
Starts the bot by connecting to the server and listening for incoming events. This method is safe to call multiple times — subsequent calls are ignored if the connection is already active.

### Method
`async`

### Returns:
- `None` - None
```

--------------------------------

### Text Container Example

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Formatting

Example of creating a Text container with nested formatting and rendering it as HTML.

```python
content = Text("Hello, ", Bold("world"))
html = content.as_html()
```

--------------------------------

### Basic Router Setup

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/types

Initializes the Router for handling events. No specific type hints are applied here.

```python
from trueconf import Router

r = Router()

@r.added_chat_participant()
async def on_added_user(event): ...
```

--------------------------------

### Install python-trueconf-bot using pip

Source: https://trueconf.github.io/python-trueconf-bot/latest

Use this command to install the library. Ensure Python 3.10+ and necessary dependencies are met.

```bash
pip install python-trueconf-bot

```

--------------------------------

### Install python-trueconf-bot

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/getting-started

Install the python-trueconf-bot package from PyPI. This will automatically install necessary dependencies like websockets, httpx, and pillow.

```bash
pip install python-trueconf-bot
```

--------------------------------

### Router Initialization and Message Handler Example

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Router

Initialize a Router instance and register a message handler using a filter. This example demonstrates how to respond to a specific text message.

```python
router = Router()

@router.message(F.text == "hello")
async def handle_hello(msg: Message):
await msg.answer("Hi there!")
```

--------------------------------

### Example: Logging Middleware

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/middleware?q=

Implement a logging middleware by inheriting from `BaseMiddleware`. This example logs the type of incoming events and a message upon completion of processing.

```python
import logging
from trueconf.middleware import BaseMiddleware

logger = logging.getLogger("bot")

class LoggingMiddleware(BaseMiddleware):
    async def __call__(self, handler, event, data):
        logger.info(f"Incoming event: {type(event).__name__}")
        await handler(event, data)
        logger.info(f"Event processed")

router.outer_middleware(LoggingMiddleware())
```

--------------------------------

### Start Bot Connection

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Bot

Starts the bot by connecting to the server and listening for incoming events. This method is asynchronous and safe to call multiple times; subsequent calls are ignored if the connection is already active.

```python
start()
```

--------------------------------

### Multi-bot Example

Source: https://trueconf.github.io/python-trueconf-bot/latest/examples

Demonstrates the simultaneous use of four different bots: an echo bot, a sick-leave bot, a monitoring bot for TrueConf Server statistics, and a GPT bot running a local LLM. This example showcases advanced integration capabilities.

```python
# This is a placeholder for the multi-bot example. The actual code is in the repository.
# View repository: 

```

--------------------------------

### Login/Password Authentication Setup

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/getting-started?q=

Use the `.from_credentials` method for login/password authentication. This method requests a new token from the server on each call.

```python
bot = Bot.from_credentials(
    username="echo_bot",
    password="123tr",
    server="10.110.2.240",
    dispatcher=dp
)
```

--------------------------------

### Install python-magic-bin on Windows

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/files

Installs the python-magic-bin package on Windows, which includes the necessary libmagic library for MIME type detection.

```bash
pip install python-magic-bin
```

--------------------------------

### Create and Activate Virtual Environment

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/getting-started

Before installing the library, create and activate a virtual environment to manage project dependencies. Use 'source' on Linux/macOS and '.venv\Scripts\activate' on Windows.

```bash
python -m venv .venv
source .venv/bin/activate # Linux / macOS
.venv\Scripts\activate # Windows PowerShell
```

--------------------------------

### Start the TrueConf Bot

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Bot?q=

Connects the bot to the server and begins listening for events. This method is idempotent and can be called multiple times.

```python
start()

```

--------------------------------

### Example: Sending a Document with FSInputFile

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Types

Demonstrates how to create an FSInputFile instance from a local file and send it as a document using the bot. Ensure the file exists at the specified path.

```python
file = FSInputFile("example.pdf")
await bot.send_document(chat_id="...", file=file)
```

--------------------------------

### Set up a Webhook Bot with FastAPI

Source: https://trueconf.github.io/python-trueconf-bot/latest/examples

This example demonstrates setting up a webhook bot using FastAPI to receive external requests, such as from Zabbix. It includes basic logging configuration and uses `uvicorn` to run the FastAPI application. The bot is initialized with server credentials.

```python
import asyncio
import logging
import os
from typing import Any
from trueconf import Bot
from contextlib import asynccontextmanager
from fastapi import FastAPI
import uvicorn

os.makedirs("logs", exist_ok=True)

logging.basicConfig(
    level=logging.DEBUG,
    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
    filename="logs/bot.log",
    encoding="utf-8",
)

@asynccontextmanager
async def lifespan(app: FastAPI):
    bot_task = asyncio.create_task(bot.run())
    yield

app = FastAPI(lifespan=lifespan)
bot = Bot.from_credentials(
    server="10.140.1.255",
    username="echo_bot",
    password="123tr",
    verify_ssl=False)


@app.post("/send")
async def read_root(data: dict[str, Any]):
    r = await bot.create_personal_chat(user_id="user")
    r = await bot.send_message(chat_id = r.chat_id, text=str(data))
    print(r.message_id)

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

```

--------------------------------

### Install python-magic for MIME type detection

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/files

Installs the python-magic package with dependencies for more accurate MIME type detection based on file content.

```bash
pip install python-trueconf-bot[python-magic]
```

--------------------------------

### Handle 'start' command to initiate form

Source: https://trueconf.github.io/python-trueconf-bot/latest/llms-full.txt

This handler is triggered by the '/start' command. It sets the initial state to 'Form.name' and prompts the user for their name.

```python
@router.message(Command("start"))
async def cmd_start(msg: Message, state: FSMContext):
await state.set_state(Form.name)
await msg.answer("What is your name?")
```

--------------------------------

### Install libmagic on Linux (Debian/Ubuntu)

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/files

Installs the libmagic system library on Debian/Ubuntu systems using apt, required for python-magic's MIME type detection.

```bash
sudo apt install libmagic1
```

--------------------------------

### Configure and run the TrueConf Bot

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/fsm?q=

Instantiate the `Bot` object using credentials and the configured dispatcher. The `main` async function then starts the bot's event loop to listen for incoming messages. Ensure `asyncio` is imported for running the main function.

```python
bot = Bot.from_credentials(
    server="your-server",
    username="your-bot",
    password="your-password",
    dispatcher=dp,
)

async def main():
    await bot.run()

import asyncio
if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Run the TrueConf Bot

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Bot

Starts the bot and handles termination signals. Set `handle_signals` to False to disable signal handling.

```python
bot.run(handle_signals=True)
```

--------------------------------

### Handle 'start' command to initiate FSM

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/fsm?q=

This handler is triggered by the '/start' command. It sets the initial FSM state to `Form.name` and prompts the user for their name. The `FSMContext` is automatically passed to the handler.

```python
@router.message(Command("start"))
async def cmd_start(msg: Message, state: FSMContext):
    await state.set_state(Form.name)
    await msg.answer("What is your name?")
```

--------------------------------

### Create an Unnamed Router

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/parse-messages

Initialize a Router instance without a specific name. This is the basic setup for handling updates.

```python
from trueconf import Router

r = Router()
```

--------------------------------

### Basic Message Handler Setup

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/shortcuts?q=

Sets up a basic message handler using the Router and Message types from the trueconf library. The handler simply acknowledges receipt of a message.

```python
from trueconf import Router
from trueconf.types import Message

r = Router()

@r.message()
async def on_message(message: Message):
    await message.answer("Message received")

```

--------------------------------

### Logging Middleware Example

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/middleware

Implement a logging middleware to record incoming events and processing completion. This middleware runs before filters and handlers.

```python
import logging
from trueconf.middleware import BaseMiddleware

logger = logging.getLogger("bot")

class LoggingMiddleware(BaseMiddleware):
async def __call__(self, handler, event, data):
logger.info(f"Incoming event: {type(event).__name__}")
await handler(event, data)
logger.info(f"Event processed")

router.outer_middleware(LoggingMiddleware())
```

--------------------------------

### Handler Priority Example

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/parse-messages?q=

Demonstrates how multiple handlers with the same filter are processed. Only the first matching handler will be executed.

```python
@r.message(F.text == "Hello")
async def handler1(message):
    await message.answer("First")

@r.message(F.text == "Hello")
async def handler2(message):
    await message.answer("Second")

```

--------------------------------

### Handler Priority Example

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/parse-messages

Demonstrates how multiple handlers with the same filter are processed. Only the first matching handler is executed.

```python
r = Router()

@r.message(F.text == "Hello")
async def handler1(message):
    await message.answer("First")

@r.message(F.text == "Hello")
async def handler2(message):
    await message.answer("Second")
```

--------------------------------

### File Handling with FileReadyState

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/enums?q=

Check the file's ready state using the FileReadyState enum before downloading. This example demonstrates checking if a file is READY or NOT_AVAILABLE.

```python
from trueconf.enums import FileReadyState

info = await bot.get_file_info(file_id="abc123")

if info.ready_state == FileReadyState.READY:
    await bot.download_file_by_id(info.file_id, "./downloads")
elif info.ready_state == FileReadyState.NOT_AVAILABLE:
    print("File is not available")

```

--------------------------------

### Send Document with BufferedInputFile

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Types?q=

Example of sending a document using a BufferedInputFile instance. Ensure the chat_id is correctly specified.

```python
await bot.send_document(chat_id="...", file=file)
```

--------------------------------

### Start a New Support Report

Source: https://trueconf.github.io/python-trueconf-bot/latest/examples

Handles the /report command to initiate a new support ticket. It generates a unique ticket number, creates a new router for the user's messages, and sets up storage for messages.

```python
@r1.message(Command("report"))
async def on_report(msg: Message):
    number = uuid.uuid4() # генерация номера обращения с помощью uuid
    await msg.answer(f"Your ticket number is {number}. All subsequent messages will be added to this ticket.")
    r = Router(name=str(number))
    dp.include_router(r)
    r.message(F.from_user.id == msg.from_user.id)(handle_report)
    router_list_for_report.update({msg.from_user.id: r})
    list_message_for_report.update({msg.from_user.id: []})

```

--------------------------------

### Initialize TrueConf Bot and Routers

Source: https://trueconf.github.io/python-trueconf-bot/latest/examples

Sets up the bot with credentials, a dispatcher, and includes a main router. This is the entry point for the bot's functionality.

```python
import asyncio
import uuid
import trueconf
from trueconf import *
from trueconf.filters import Command

r1 = Router()
dp = Dispatcher()
dp.include_router(r1)

router_list_for_report = {}
list_message_for_report = {}

bot = trueconf.Bot.from_credentials(
    server="10.110.2.241",
    username="report_bot",
    password="123tr",
    dispatcher=dp,
    https=True,
    verify_ssl=False)

```

--------------------------------

### Basic Text Filter Example

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/filters

Use this filter to trigger a handler when a message's text exactly matches a specific string. No additional setup is required beyond importing MagicFilter.

```python
F.text == "ping"
```

--------------------------------

### Run the TrueConf bot

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Bot?q=

The `run` method starts the bot's main loop, waiting for events. It can optionally handle termination signals for graceful shutdown.

```python
run(handle_signals=True)
```

--------------------------------

### Middleware Inheritance Example

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/middleware

Demonstrates how middleware registered on a parent router is inherited by child routers. The parent's middleware runs before the child's middleware and handlers.

```python
parent = Router()
parent.outer_middleware(LoggingMiddleware())

child = Router()
parent.include_router(child)
```

--------------------------------

### Initialize Dispatcher, Router, and Storage

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/fsm?q=

Set up the bot's core components: MemoryStorage for state persistence during development, a Dispatcher to manage updates, and a Router to direct incoming messages. The router is then included in the dispatcher.

```python
storage = MemoryStorage()
dp = Dispatcher(storage=storage)
router = Router()
dp.include_router(router)
```

--------------------------------

### Run the TrueConf Bot

Source: https://trueconf.github.io/python-trueconf-bot/latest/examples

The main execution block that starts the TrueConf bot using asyncio. This should be the last part of the script to run.

```python
if __name__ == "__main__":
    asyncio.run(bot.run())

```

--------------------------------

### FSM Strategy Initialization

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/fsm

Example of initializing a Dispatcher with a specific FSM strategy. The CHAT strategy is used here, which means the entire chat shares a single state.

```python
from trueconf.fsm import FSMStrategy
from aiogram import Dispatcher
from aiogram.fsm.storage.memory import MemoryStorage

dp = Dispatcher(storage=MemoryStorage(), strategy=FSMStrategy.CHAT)
```

--------------------------------

### File Handling with FileReadyState Enum

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/enums

Check the ready state of a file using the FileReadyState enum before downloading. This example demonstrates handling both ready and unavailable file states.

```python
from trueconf.enums import FileReadyState

info = await bot.get_file_info(file_id="abc123")

if info.ready_state == FileReadyState.READY:
await bot.download_file_by_id(info.file_id, "./downloads")
elif info.ready_state == FileReadyState.NOT_AVAILABLE:
print("File is not available")

```

--------------------------------

### Install libmagic on macOS

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/files

Installs the libmagic system library on macOS using Homebrew, required for python-magic's MIME type detection.

```bash
brew install libmagic
```

--------------------------------

### Initialize Router and Dispatcher

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/getting-started

Create instances of Router and Dispatcher and connect them. The Dispatcher handles incoming events, and the Router directs them to appropriate handlers.

```python
r = Router()
dp = Dispatcher()
# dp.include_router(r)
```

--------------------------------

### Import Required Classes

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/getting-started

Import the necessary classes from the trueconf library to start building your bot. This includes Bot, Dispatcher, Router, F, and Message types.

```python
from trueconf import Bot, Dispatcher, Router, F
from trueconf.types import Message
```

--------------------------------

### Initialize GetFileInfoResponse

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Responses

Create a GetFileInfoResponse with file details and optional download URL and previews.

```python
GetFileInfoResponse(name, size, mimetype, ready_state, file_id, previews=None, download_url=None)
```

--------------------------------

### Initialize TrueConf Router

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/parse-messages?q=

Create an instance of the Router to manage message handling logic.

```python
from trueconf import Router

r = Router()
```

```python
from trueconf import Router

r = Router(name="Router1")
```

--------------------------------

### Import necessary modules for TrueConf Bot FSM

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/fsm?q=

Import the core Bot, Dispatcher, Router, FSM components, and Message types. This setup is required for any TrueConf bot utilizing FSM.

```python
from trueconf import Bot, Dispatcher, Router, F
from trueconf.types import Message
from trueconf.filters import Command
from trueconf.fsm import FSMContext, State, StatesGroup, StateFilter
from trueconf.fsm.storage.memory import MemoryStorage
```

--------------------------------

### Example FSM Usage with StateFilter

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/fsm

This example demonstrates how to use StateFilter to restrict a handler to a specific state within an FSM. It assumes the existence of a router and a Form state group with a 'name' state.

```python
from aiogram.dispatcher.filters.state import State, StatesGroup
from aiogram.dispatcher.filters import StateFilter


class Form(StatesGroup):
    name = State()
    age = State()
    confirm = State()


@dp.message_handler(state=Form.name)
async def process_name(message: types.Message):
    await state.update_data(name=message.text)
    await Form.next()
    await message.reply("What is your age?")


@dp.message_handler(stateFilter=Form.name)
async def process_name_incorrectly(message: types.Message):
    # This handler will not be called because the state is Form.name
    # and the previous handler is already registered for this state.
    # This is an example of how StateFilter works.
    await message.reply("Something went wrong. Please try again.")

```

--------------------------------

### Run the TrueConf Bot

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/fsm

Initialize the TrueConf Bot with credentials and the dispatcher, then run the bot using asyncio. The `FSMContext` is automatically injected into handlers.

```python
bot = Bot.from_credentials(
server="your-server",
username="your-bot",
password="your-password",
dispatcher=dp,
)

async def main():
await bot.run()

import asyncio
if __name__ == "__main__":
asyncio.run(main())
```

--------------------------------

### Create BufferedInputFile from disk

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Types

Use BufferedInputFile.from_file for convenient file loading from disk. File name and size are auto-detected if not provided.

```python
from_file(path, file_name=None, file_size=None, mime_type=None, **kwargs)
```

--------------------------------

### Get Bot's Personal Chat ID (Alternative) - Python

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Bot

An alternative method to get the chat ID for the bot's personal 'Favorites' chat. It also creates the chat if it doesn't exist and caches the result.

```python
me_chat()
```

--------------------------------

### Create Bot Instance from Credentials

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Bot

Initializes a bot instance using server details, username, and password for authentication. Optional parameters allow configuration for message reception and SSL verification.

```python
from_credentials(server, username, password, *, dispatcher=None, receive_unread_messages=False, receive_system_messages=False, skip_self_messages=True, verify_ssl=True, web_port=None, https=True, ws_max_retries=5, ws_max_delay=60, debug=False, on_health_check=None, timeout=10.0)
```

--------------------------------

### URLInputFile url attribute

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Types?q=

Sets or gets the URL of the file to download.

```python
url = url
```

--------------------------------

### URLInputFile headers attribute

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Types?q=

Sets or gets the optional HTTP headers for the request.

```python
headers = headers
```

--------------------------------

### Get Message by ID

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Bot

Retrieves a specific message using its unique identifier.

```python
get_message_by_id(message_id)
```

--------------------------------

### Get Server Version

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Bot?q=

Retrieves the domain name of the connected TrueConf server.

```python
await bot.server_version()
```

--------------------------------

### Get Server Name

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Bot?q=

Retrieves the domain name of the connected TrueConf server.

```python
await bot.server_name()
```

--------------------------------

### Get File Info

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Bot?q=

Retrieves metadata for a file using its unique identifier.

```python
get_file_info(file_id)
```

--------------------------------

### Get Chat by ID

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Bot?q=

Retrieves information about a specific chat using its unique identifier.

```python
get_chat_by_id(chat_id)
```

--------------------------------

### Bot Initialization with Credentials

Source: https://trueconf.github.io/python-trueconf-bot/latest/features?q=

Initialize the Bot instance using server, username, and password for authentication. This method is an alternative to using a JWT token.

```python
bot = Bot.from_credentials(server, username, password)

```

--------------------------------

### Get All User Data

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/fsm?q=

Retrieves a dictionary containing all data saved for the current user.

```python
data = await state.get_data()
```

--------------------------------

### Initialize Bot with Credentials

Source: https://trueconf.github.io/python-trueconf-bot/latest/features

Authenticate with the TrueConf server using username and password. This method is an alternative to using a JWT token.

```python
bot = Bot.from_credentials(server, username, password)
```

--------------------------------

### Get Server Name

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Bot

Retrieves the domain name of the connected TrueConf server. This method is asynchronous.

```python
server_name()
```

--------------------------------

### Get message text

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Types?q=

Retrieves the text content of the message. Returns None if the message has no text.

```python
text
```

--------------------------------

### Bot Initialization

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Bot

Initializes and connects a TrueConf bot to the server with specified authentication and connection parameters.

```APIDOC
## Bot Initialization

### Description
Initializes a new bot instance and establishes a connection to the TrueConf server using provided credentials and configuration options.

### Parameters
#### Required Parameters
- **server** (str): Address of the TrueConf server.
- **username** (str): Username for authentication.
- **password** (str): Password for authentication.

#### Optional Parameters
- **dispatcher** (trueconf.Dispatcher): Dispatcher instance for registering handlers. Defaults to None.
- **receive_unread_messages** (bool): Whether to receive unread messages on connection. Defaults to False.
- **receive_system_messages** (bool): Whether to receive system messages. Defaults to False.
- **skip_self_messages** (bool): If True, the bot will ignore messages sent by itself. Defaults to True.
- **verify_ssl** (bool | str | SSLContext): SSL verification mode. Defaults to True.
- **web_port** (int): WebSocket connection port. Defaults to 443.
- **https** (bool): Whether to use HTTPS protocol. Defaults to True.
- **ws_max_retries** (int): Max connection attempts on network/IP errors. Defaults to 5.
- **ws_max_delay** (int): Maximum delay between reconnection attempts (in seconds). Defaults to 60.
- **debug** (bool): Enables debug mode. Defaults to False.
- **on_health_check** (HealthCheckCallback | None): Async callback called when the bot connection health changes. Defaults to None.
- **timeout** (float | int): The maximum time in seconds to wait for network activity. Defaults to 10.0.

### Returns
- **Bot** (Self): An authorized bot instance.

### Raises
- **RuntimeError**: If the token could not be obtained.
```

--------------------------------

### URLInputFile verify_ssl attribute

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Types?q=

Sets or gets whether to verify SSL certificates for the HTTP request.

```python
verify_ssl = verify_ssl
```

--------------------------------

### Initialize Router and Define Message Handler

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/shortcuts

Sets up the router and defines an asynchronous handler for incoming messages. The handler receives a Message object and sends a confirmation.

```python
from trueconf import Router
from trueconf.types import Message

r = Router()

@r.message()
async def on_message(message: Message):
    await message.answer("Message received")
```

--------------------------------

### get_chat_history

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Bot?q=

Fetches the message history for a given chat, with options to specify the number of messages and a starting point.

```APIDOC
## get_chat_history

### Description
Retrieves the message history of the specified chat.

### Method Signature
`async get_chat_history(chat_id: str, count: int, from_message_id: str | None = None)`

### Parameters
#### Path Parameters
- **chat_id** (str) - Required - Identifier of the chat.
- **count** (int) - Required - Number of messages to retrieve.
- **from_message_id** (str | None) - Optional - Identifier of the message to start retrieving history from. If not specified, the history will be loaded from the most recent message.

### Returns
- **GetChatHistoryResponse** (GetChatHistoryResponse) - Object containing the result of the chat history request.

### Raises
- **ValueError** - If the count number is less than 1.
```

--------------------------------

### Initialize GetFileUploadLimitsResponse

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Responses

Create a GetFileUploadLimitsResponse with extensions and an optional max size.

```python
GetFileUploadLimitsResponse(extensions, max_size=None)
```

--------------------------------

### Get Message Author

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Types

Retrieve the author of the current message. This provides a shortcut to access the `EnvelopeAuthor` object.

```python
from_user
```

--------------------------------

### Initialize Dispatcher with FSM Storage

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Dispatcher

Initialize the Dispatcher with a MemoryStorage backend for FSM management.

```python
from trueconf.fsm.storage.memory import MemoryStorage

storage = MemoryStorage()
dp = Dispatcher(storage=storage)
```

--------------------------------

### Initialize AuthResponsePayload

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Responses

Create an AuthResponsePayload with user and connection IDs.

```python
AuthResponsePayload(user_id, connection_id)
```

--------------------------------

### URLInputFile.clone()

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Types

Creates a clone of the current URLInputFile instance. This is useful when the same file needs to be reused, for example, when sending a preview.

```APIDOC
## `clone`

### Description
Creates a clone of the current `URLInputFile` instance.

Useful when the same file needs to be reused (e.g., sending a preview). The cloned object retains the same URL, headers, and metadata.

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `URLInputFile` | `` trueconf.types.URLInputFile (`trueconf.types.input_file.URLInputFile`)' href=#trueconf.types.URLInputFile>URLInputFile | A new instance with identical parameters. |
```

--------------------------------

### Initialize Bot with JWT Token

Source: https://trueconf.github.io/python-trueconf-bot/latest/features

Connect to the TrueConf server using a pre-obtained JWT token. Ensure the server address and token are correctly provided.

```python
bot = Bot(server="video.example.com", token="...")
```

--------------------------------

### Get sticker object

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Types?q=

Retrieves the attached sticker object if the message contains a sticker. Returns None otherwise.

```python
sticker
```

--------------------------------

### Chat Type Identification with ChatType

Source: https://trueconf.github.io/python-trueconf-bot/latest/llms-full.txt

Identify the type of chat using the ChatType enum, for example, checking if it is a group chat.

```python
from trueconf.enums import ChatType

if chat.chat_type == ChatType.GROUP:
await message.answer("This is a group chat")
```

--------------------------------

### FSInputFile Initialization

Source: https://trueconf.github.io/python-trueconf-bot/latest/llms-full.txt

Initializes an FSInputFile instance from a local file. Automatically detects file name, size, and MIME type if not explicitly provided.

```APIDOC
## FSInputFile

### Description
Represents a file uploaded from the local filesystem. Used for uploading documents, images, or any other files directly from disk. Automatically detects the file name, size, and MIME type when not explicitly provided.

### Method Signature
`FSInputFile(path, file_name=None, file_size=None, mime_type=None, **kwargs)`

### Parameters
#### Path Parameters
- **path** (str | Path) - Required - Path to the local file.
- **file_name** (str) - Optional - File name to be propagated in the upload. Defaults to None.
- **file_size** (int) - Optional - File size in bytes. Defaults to None.
- **mime_type** (str) - Optional - File MIME type. Defaults to None.

### Example
```python
file = FSInputFile("path/to/file.zip")
await bot.send_document(chat_id="...", file=file)
```
```

--------------------------------

### Get Chats

Source: https://trueconf.github.io/python-trueconf-bot/latest/llms-full.txt

Retrieves a list of available chats. This method can be used to find existing chats by their title to obtain their `chat_id`.

```APIDOC
## Get Chats

### Description
Retrieves a list of available chats. Useful for finding existing chats and their `chat_id`s, for example, by title.

### Method
Asynchronous function call.

### Parameters
#### Path Parameters
None

#### Query Parameters
- **count** (integer) - Optional - The number of chats to retrieve per page.
- **page** (integer) - Optional - The page number of the chats to retrieve.

#### Request Body
None

### Request Example
```python
response = await bot.get_chats(count=10, page=1)
```

### Response
#### Success Response
Returns a `GetChatsResponse` object containing a list of chats.

#### Response Example
```json
{
  "list": [
    {
      "chat_id": "some_chat_id_1",
      "title": "Support"
    },
    {
      "chat_id": "some_chat_id_2",
      "title": "General"
    }
  ]
}
```
```

--------------------------------

### Create BufferedInputFile from Local File

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Types?q=

Use the `from_file` class method for convenient loading of files from disk. This is useful for preparing files that might be reused or processed before sending.

```python
BufferedInputFile.from_file(path, file_name=None, file_size=None, mime_type=None, **kwargs)
```

--------------------------------

### Get video object

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Types?q=

Retrieves the attached video object if the message contains a video. This is a shortcut for accessing video metadata.

```python
video
```

--------------------------------

### Initialize Bot Instance

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Bot?q=

Initialize a TrueConf chatbot instance with server address and authorization token. Keyword-only arguments allow for detailed configuration of connection and message handling.

```python
Bot(server, token, *, dispatcher=None, receive_unread_messages=False, receive_system_messages=False, skip_self_messages=True, verify_ssl=True, web_port=None, https=True, ws_max_retries=5, ws_max_delay=60, debug=False, on_health_check=None, timeout=10.0)
```

--------------------------------

### Get Chat Participant

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Bot?q=

Retrieves information about a specific participant within a chat. The user ID can be provided with or without a domain.

```python
get_chat_participant(chat_id, user_id)
```

--------------------------------

### Initialize CreateP2PChatResponse

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Responses

Create a CreateP2PChatResponse with a chat ID.

```python
CreateP2PChatResponse(chat_id)
```

--------------------------------

### FSInputFile Constructor

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Types?q=

Initializes an FSInputFile instance from a local file path. File name, size, and MIME type are auto-detected if not provided.

```python
FSInputFile(path, file_name=None, file_size=None, mime_type=None, **kwargs)
```

--------------------------------

### Send a formatted text message

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Types

Send a message with text formatting using a specified parse mode. Markdown is used in this example.

```python
>>> @.message()
>>> async def on_message(message:Message):
>>> await message.answer("Hi, **there!", parse_mode=ParseMode.MARKDOWN)
```

--------------------------------

### Bot Initialization with JWT Token

Source: https://trueconf.github.io/python-trueconf-bot/latest/features?q=

Initialize the Bot instance using a pre-obtained JWT token. Ensure the server address is correctly specified.

```python
bot = Bot(server="video.example.com", token="...")

```

--------------------------------

### Initialize Router and Dispatcher

Source: https://trueconf.github.io/python-trueconf-bot/latest/llms-full.txt

Create instances of Router and Dispatcher and connect them to manage message handling and dispatching within your TrueConf bot application.

```python
r = Router()
dp = Dispatcher()
```

--------------------------------

### Get Message Content Type

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Types

Retrieve the type of the current message content. Use this to determine if a message is text, an attachment, etc.

```python
content_type
```

--------------------------------

### URLInputFile.read()

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Types

Downloads the file content from the remote URL. This method performs a full GET request and returns the content as raw bytes.

```APIDOC
## `read` (async)

### Description
Downloads the file content from the remote URL.

Performs a full GET request and returns the content as raw bytes.

### Returns

| Name | Type | Description |
| --- | --- | --- |
| `bytes` | | File content. |
```

--------------------------------

### Get User Display Name

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Bot

Retrieves the display name of a user by their TrueConf ID. The user ID can be provided with or without a domain.

```python
get_user_display_name(user_id)
```

--------------------------------

### from_credentials

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Bot?q=

Creates and authorizes a bot instance using server address, username, and password. This method is the primary way to connect a bot to the TrueConf server.

```APIDOC
## from_credentials

### Description
Creates a bot instance using username and password authentication.

### Method
`classmethod`

### Parameters
#### Path Parameters
- **server** (str) - Required - Address of the TrueConf server.
- **username** (str) - Required - Username for authentication.
- **password** (str) - Required - Password for authentication.
#### Query Parameters
- **dispatcher** (Dispatcher | None) - Optional - Dispatcher instance for registering handlers. Defaults to None.
- **receive_unread_messages** (bool) - Optional - Whether to receive unread messages on connection. Defaults to False.
- **receive_system_messages** (bool) - Optional - Whether to receive system messages. Defaults to False.
- **skip_self_messages** (bool) - Optional - If True, the bot will ignore messages sent by itself. Defaults to True.
- **verify_ssl** (bool | str | SSLContext) - Optional - SSL verification mode. Defaults to True.
- **web_port** (int) - Optional - WebSocket connection port. Defaults to 443.
- **https** (bool) - Optional - Whether to use HTTPS protocol. Defaults to True.
- **ws_max_retries** (int) - Optional - Max connection attempts on network/IP errors before giving up. Defaults to 5.
- **ws_max_delay** (int) - Optional - Maximum delay between reconnection attempts (in seconds). Defaults to 60.
- **debug** (bool) - Optional - Enables debug mode. Defaults to False.
- **on_health_check** (HealthCheckCallback | None) - Optional - Async callback called when the bot connection health changes. Defaults to None.
- **timeout** (float | int) - Optional - The maximum time in seconds to wait for network activity. Defaults to 10.0.

### Response
#### Success Response
- **Bot** (Self) - An authorized bot instance.

### Raises
- **RuntimeError** - If the token could not be obtained.
```

--------------------------------

### Get Specific User Data Value

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/fsm

Retrieves a specific data value by its key. A default value can be provided if the key does not exist.

```python
name = await state.get_value("name")
```

```python
name = await state.get_value("name", "Not specified")
```

--------------------------------

### Initialize Dispatcher with CHAT FSM Strategy

Source: https://trueconf.github.io/python-trueconf-bot/latest/llms-full.txt

Demonstrates how to initialize the Dispatcher with a specific FSM strategy. The CHAT strategy is used when all users in a chat should share a single state, suitable for polls or collaborative games.

```python
from trueconf.fsm import FSMStrategy
from aiogram import Dispatcher
from aiogram.storage.memory import MemoryStorage

dp = Dispatcher(storage=MemoryStorage(), strategy=FSMStrategy.CHAT)
```

--------------------------------

### Handling Changed Participant Role Events

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Types

Example of how to use the ChangedParticipantRole event type in a handler function to process role changes in a chat.

```python
from trueconf.types import ChangedParticipantRole

@router.changed_chat_participant_role()
async def on_role_changed(event: ChangedParticipantRole):
print(f"User {event.user_id} now has role {event.role} in chat {event.chat_id}")
```

--------------------------------

### Initialize Mention Node

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Formatting

Represents a TrueConf user mention. Use this to create a mention node with a label and a user ID.

```python
Mention(*body, user_id)
```

--------------------------------

### URLInputFile prepare method

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Types?q=

Prepares file metadata by sending a HEAD request to the specified URL. Attempts to detect MIME type, file size, and file name from HTTP headers and URL path. Raises ValueError if Content-Length is invalid.

```python
prepare()
```

--------------------------------

### Get Chat ID from Incoming Message

Source: https://trueconf.github.io/python-trueconf-bot/latest/llms-full.txt

Explains how to obtain a `chat_id` from an incoming message by handling messages with a bot router and printing the `message.chat_id`.

```APIDOC
## Get Chat ID from Incoming Message

### Description
Obtains the `chat_id` from an incoming message by setting up a message handler using `trueconf.Router`. This is particularly useful for group chats and channels.

### Method
Asynchronous function decorated with `@router.message()`.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from trueconf import Router
from trueconf.types import Message

router = Router()

@router.message()
async def print_chat_id(message: Message):
print(message.chat_id)
```

### Response
#### Success Response
Prints the `chat_id` of the incoming message to the console.

#### Response Example
```
some_chat_id_from_message
```
```

--------------------------------

### FSInputFile Constructor

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Types?q=

Initializes an FSInputFile instance from a local file. If not provided, file_name, file_size, and mime_type are automatically detected.

```APIDOC
## FSInputFile(path, file_name=None, file_size=None, mime_type=None, **kwargs)

### Description
Represents a file uploaded from the local filesystem. Used for uploading documents, images, or any other files directly from disk. Automatically detects the file name, size, and MIME type when not explicitly provided.

### Parameters
#### Path Parameters
- **path** (str | Path) - Required - Path to the local file.
- **file_name** (str) - Optional - File name to be propagated in the upload. Defaults to None.
- **file_size** (int) - Optional - File size in bytes. Defaults to None.
- **mime_type** (str) - Optional - File MIME type. Defaults to None.

### Example
```python
file = FSInputFile("path/to/file.zip")
await bot.send_document(chat_id="...", file=file)
```
```

--------------------------------

### Get Specific User Data Value

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/fsm?q=

Retrieves a specific data value for the user using its key. Useful when only one field is needed.

```python
name = await state.get_value("name")
```

--------------------------------

### Handle AddedChatParticipant events

Source: https://trueconf.github.io/python-trueconf-bot/latest/llms-full.txt

Example of how to use the @.added_chat_participant() decorator to create a handler for when a user is added to a chat. It prints the user ID of the added participant.

```python
from trueconf.types import AddedChatParticipant

@.added_chat_participant()
async def on_added(event: AddedChatParticipant):
print(event.user_id)

```

--------------------------------

### Initialize Dispatcher

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Dispatcher?q=

Instantiate the Dispatcher class. It can be configured with optional storage, FSM manager, key builder, and strategy parameters.

```python
dispatcher = Dispatcher()
```

--------------------------------

### Find Chat by Title using Generator

Source: https://trueconf.github.io/python-trueconf-bot/latest/llms-full.txt

An example of how to find a specific chat by its title from the list of chats obtained using `bot.get_chats()`, utilizing a generator.

```APIDOC
## Find Chat by Title (Generator)

### Description
Finds a specific chat by its title from the list of chats retrieved by `bot.get_chats()`, using a generator expression for efficient searching.

### Method
Iterating over the result of `bot.get_chats()`.

### Parameters
None directly for this snippet, relies on `bot.get_chats()` parameters.

### Request Example
```python
response = await bot.get_chats(count=100, page=1)

chat = next(
(chat for chat in response.list if chat.title == "Support"),
None,
)

if chat is not None:
print(chat.chat_id)
```

### Response
#### Success Response
Prints the `chat_id` of the found chat, or nothing if the chat is not found.

#### Response Example
```
some_chat_id
```
```

--------------------------------

### Initialize ChangeParticipantRoleResponse

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Responses

Use this constructor to create an instance of ChangeParticipantRoleResponse.

```python
ChangeParticipantRoleResponse()
```

--------------------------------

### Handle File Upload Progress

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Types?q=

Example of an event handler function that processes UploadingProgress events. It prints the file ID and the number of bytes uploaded.

```python
from trueconf.types import UploadingProgress

@<router>.uploading_progress()
async def on_progress(event: UploadingProgress):
    print(f"File {event.file_id}: uploaded {event.progress} bytes")
```

--------------------------------

### Initialize Bot with Credentials

Source: https://trueconf.github.io/python-trueconf-bot/latest/llms-full.txt

Initializes the TrueConf bot with server details, username, password, and a dispatcher. The `on_health_check` callback is used to handle status updates.

```python
bot = Bot.from_credentials(
server="video.example.com",
username="echo_bot",
password="123tr",
dispatcher=dp,
on_health_check=on_health_check,
)
```

--------------------------------

### AddedChatParticipant Dataclass Example

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Types?q=

Demonstrates how to use the AddedChatParticipant dataclass as an event type in a handler function. This event is triggered when a new participant is added to a chat.

```python
from trueconf.types import AddedChatParticipant

@<router>.added_chat_participant()
async def on_added(event: AddedChatParticipant):
    print(event.user_id)

```

--------------------------------

### FileReadyState READY

Source: https://trueconf.github.io/python-trueconf-bot/latest/llms-full.txt

Indicates that a file is ready on the server.

```python
READY = 2

```

--------------------------------

### Get Bot Health Status - Python

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Bot

Retrieves the current operational status of the bot, including WebSocket and authorization states. Useful for external monitoring.

```python
health_check()
```

--------------------------------

### Import Bot Class

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Responses?q=

Import the main Bot class from the trueconf library.

```python
from trueconf import Bot
```

--------------------------------

### Get Bot Token

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Bot?q=

Retrieve the bot's authorization token using the 'token' property. This token is essential for authenticating the bot with the TrueConf server.

```python
token
```

--------------------------------

### BufferedInputFile.from_file()

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Types?q=

Creates a BufferedInputFile from a file on disk. This is a convenient way to load a file into memory.

```APIDOC
### from_file(path, file_name=None, file_size=None, mime_type=None, **kwargs)

Creates a `BufferedInputFile` from a file on disk.
This is a convenient way to load a file into memory if it needs to be reused or processed before sending.

### Parameters
#### Path Parameters
- **path** (str | Path) - Required - Path to the local file.
- **file_name** (str) - Optional - File name to propagate. Defaults to the name extracted from path. Defaults to None.
- **file_size** (int) - Optional - File size in bytes. Auto-detected if not specified. Defaults to None.
- **mime_type** (str) - Optional - MIME type of the file. Auto-detected if not specified. Defaults to None.

Returns:
- **BufferedInputFile**: A new instance ready for upload.
```

--------------------------------

### Get Current User State

Source: https://trueconf.github.io/python-trueconf-bot/latest/learn/fsm?q=

Retrieves the current state of the user. Returns the state identifier (e.g., 'Form:name') or None if no state is active.

```python
current = await state.get_state()
```

--------------------------------

### Bot Initialization

Source: https://trueconf.github.io/python-trueconf-bot/latest/reference/Bot?q=

Initializes a TrueConf chatbot instance with WebSocket connection and configuration options. All following arguments must be passed by name (keyword-only).

```APIDOC
## Bot(server, token, *, dispatcher=None, receive_unread_messages=False, receive_system_messages=False, skip_self_messages=True, verify_ssl=True, web_port=None, https=True, ws_max_retries=5, ws_max_delay=60, debug=False, on_health_check=None, timeout=10.0)

### Description
Initializes a TrueConf chatbot instance with WebSocket connection and configuration options.

### Parameters
#### Path Parameters
- **server** (str) - Required - Address of the TrueConf server.
- **token** (str) - Required - Bot authorization token.

#### Keyword-Only Parameters
- **dispatcher** (Dispatcher | None) - Optional - Dispatcher instance for registering handlers. Defaults to None.
- **receive_unread_messages** (bool) - Optional - Whether to receive unread messages on connection. Defaults to False.
- **receive_system_messages** (bool) - Optional - Whether to receive system messages, such as user additions to the chat or chat title changes. Defaults to False.
- **skip_self_messages** (bool) - Optional - If True, the bot will ignore messages sent by itself. This prevents echo loops when multiple bot sessions are running. Defaults to True.
- **verify_ssl** (bool | str | SSLContext) - Optional - SSL verification mode. If True, verifies the server certificate using the system trust store when available. If False, disables certificate verification. If a string is provided, it must be a path to a CA bundle file. A custom ssl.SSLContext can also be passed. Defaults to True.
- **web_port** (int) - Optional - WebSocket connection port. Defaults to 443.
- **https** (bool) - Optional - Whether to use HTTPS protocol. Defaults to True.
- **ws_max_retries** (int) - Optional - Max connection attempts on network/IP errors before giving up. Defaults to 5.
- **ws_max_delay** (int) - Optional - Maximum delay between reconnection attempts (in seconds). Defaults to 60.
- **debug** (bool) - Optional - Enables debug mode. Defaults to False.
- **on_health_check** (HealthCheckCallback | None) - Optional - Async callback called when the bot connection health changes. The callback receives a dictionary with the current status, WebSocket state, authorization state, server, port, protocol, timestamp, and optional error details. Defaults to None.
- **timeout** (float | int) - Optional - The maximum time in seconds to wait for network activity. Instead of limiting the total upload duration, it protects against socket freezes during data transmission and waiting for the server's response. Defaults to 10.0.

### Note
Alternatively, you can authorize using a username and password via the `from_credentials()` class method.
Source: trueconf.com/docs/chatbot-connector/en/connect-and-auth/#auth
```
Tokens:
Raw