Clients¶

Выбор между MaxClient и SocketMaxClient¶

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

Сравнение клиентов¶
Функция	MaxClient (WebSocket)	SocketMaxClient (Socket)
Протокол подключения	WebSocket	TCP Socket
Способ авторизации	Вход по QR-коду	Вход/регистрация по номеру телефона
Регистрация новых пользователей	❌ Не поддерживается	✅ Поддерживается
Скорость подключения	Быстрое	Медленнее
Рекомендуемое использование	Базовые боты и приложения	Массовая регистрация, системная авторизация

MaxClient¶

Основной асинхронный WebSocket клиент для взаимодействия с Max API.

Поддерживаемые методы авторизации:

✅ Вход по QR-коду (WEB device_type)
❌ Вход по номеру телефона (больше не поддерживается)
❌ Регистрация по номеру телефона

Инициализация:

from pymax import MaxClient

client = MaxClient(
    phone="+79001234567",           # Номер телефона (обязательно)
    work_dir="./cache",             # Папка для кэша сессии
    reconnect=True,                 # Автоматическое переподключение
    send_fake_telemetry=True,       # Отправлять телеметрию
    logger=None,                    # Пользовательский логгер
)

Note

MaxClient по умолчанию использует WEB device_type и поддерживает только вход по QR-коду. Это является рекомендуемым способом авторизации для большинства приложений.

Основные методы:

# Запустить клиент
await client.start()

# Закрыть клиент
await client.close()

# Получить информацию о чате
chat = await client.get_chat(chat_id=123456)
chats = await client.get_chats([123, 456])

# Получить информацию о пользователе
user = await client.get_user(user_id=789012)

# Отправить сообщение
result = await client.send_message(
    chat_id=123456,
    text="Сообщение"
)

# Редактировать сообщение
await client.edit_message(
    chat_id=123456,
    message_id=msg_id,
    text="Новый текст"
)

# Удалить сообщение
await client.delete_message(
    chat_id=123456,
    message_id=msg_id
)

# Получить историю сообщений
history = await client.fetch_history(
    chat_id=123456,
    limit=50
)

# Изменить профиль с загрузкой фото
result = await client.change_profile(
    first_name="Иван",
    last_name="Петров",
    description="Привет!",
    photo=Photo(...)  # Новая фотография профиля
)

# Разрешить группу по ссылке
group = await client.resolve_group_by_link(
    link="https://max.app/g/ABC123"
)

Свойства:

client.me                   # Информация о себе (Me)
client.is_connected         # Статус подключения (bool)
client.chats                # Список всех чатов (list[Chat])
client.dialogs              # Список диалогов (list[Dialog])
client.channels             # Список каналов (list[Channel])
client.phone                # Номер телефона (str)
client.token                # Токен сессии (str | None)
client.contacts             # Список контактов (list[User])

Обработчики событий:

@client.on_start
async def on_start():
    """При запуске клиента"""
    pass


@client.on_message()
async def on_message(message: Message):
    """При получении сообщения"""
    pass

Контекстный менеджер:

async with MaxClient(phone="+79001234567") as client:
    # Клиент автоматически подключён
    await client.send_message(chat_id=123456, text="Привет!")
    # Клиент автоматически закроется

Автоматическое подключение/отключение:

client = MaxClient(phone="+79001234567", reconnect=True)

# Клиент автоматически переподключится при разрыве соединения
await client.start()

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

class pymax.MaxClient(phone, uri='wss://ws-api.oneme.ru/websocket', session_name='session.db', headers=None, token=None, send_fake_telemetry=True, host='api.oneme.ru', port=443, proxy=None, work_dir='.', registration=False, first_name='', last_name=None, device_id=None, logger=None, reconnect=True, reconnect_delay=1.0)[source]¶

Bases: ApiMixin, WebSocketMixin, BaseClient

Parameters:

phone (str)
uri (str)
session_name (str)
headers (UserAgentPayload | None)
token (str | None)
send_fake_telemetry (bool)
host (str)
port (int)
proxy (str | Literal[True] | None)
work_dir (str)
registration (bool)
first_name (str)
last_name (str | None)
device_id (UUID | None)
logger (logging.Logger | None)
reconnect (bool)
reconnect_delay (float)

CHUNK_SIZE = 6291456¶

add_chat_update_handler(handler)¶

Добавляет обработчик обновления информации о чате.

Parameters:: handler (Callable[[Chat], Any | Awaitable[Any]]) -- Функция или coroutine с аргументом (chat: Chat).
Returns:: Установленный обработчик.
Return type:: Callable[[Chat], Any | Awaitable[Any]]

async add_contact(contact_id)¶

Добавляет контакт в список контактов

Parameters:: contact_id (int) -- ID контакта
Returns:: Объект контакта
Return type:: Contact
Raises:: ResponseStructureError -- Если структура ответа неверна

add_message_handler(handler, filter=None)¶

Добавляет обработчик входящих сообщений.

Parameters:

handler (Callable[[Message], Any | Awaitable[Any]]) -- Обработчик.
filter (BaseFilter[Message] | None) -- Фильтр. По умолчанию None.

Returns:

Обработчик.

Return type:

Callable[[Message], Any | Awaitable[Any]]

add_on_start_handler(handler)¶

Добавляет обработчик, вызываемый при старте клиента.

Parameters:: handler (Callable[[], Any | Awaitable[Any]]) -- Функция или coroutine без аргументов.
Returns:: Установленный обработчик.
Return type:: Callable[[], Any | Awaitable[Any]]

add_raw_receive_handler(handler)¶

Добавляет обработчик для получения необработанных данных от сервера.

Parameters:: handler (Callable[[dict[str, Any]], Any | Awaitable[Any]]) -- Функция или coroutine с аргументом (data: dict).
Returns:: Установленный обработчик.
Return type:: Callable[[dict[str, Any]], Any | Awaitable[Any]]

async add_reaction(chat_id, message_id, reaction)¶

Добавляет реакцию к сообщению.

Parameters:

chat_id (int) -- ID чата
message_id (str) -- ID сообщения
reaction (str (emoji)) -- Реакция для добавления

Returns:

Объект ReactionInfo или None

Return type:

ReactionInfo | None

add_reaction_change_handler(handler)¶

Добавляет обработчик изменения реакций на сообщения.

Parameters:: handler (Callable[[str, int, ReactionInfo], Any | Awaitable[Any]]) -- Функция или coroutine с аргументами (message_id: str, chat_id: int, reaction_info: ReactionInfo).
Returns:: Установленный обработчик.
Return type:: Callable[[str, int, ReactionInfo], Any | Awaitable[Any]]

add_scheduled_task(handler, interval)¶

Добавляет периодическую задачу.

Parameters:

handler (Callable[[], Any | Awaitable[Any]]) -- Функция или coroutine без аргументов.
interval (float) -- Интервал выполнения в секундах.

Returns:

Установленный обработчик.

Return type:

Callable[[], Any | Awaitable[Any]]

allowed_device_types: set[str] = {'WEB'}¶

Основной клиент для работы с WebSocket API сервиса Max.

Parameters:

phone (str) -- Номер телефона для авторизации.
uri (str, optional) -- URI WebSocket сервера.
session_name (str, optional) -- Название сессии для хранения базы данных.
work_dir (str, optional) -- Рабочая директория для хранения базы данных.
logger (logging.Logger | None) -- Пользовательский логгер. Если не передан, используется логгер модуля с именем f"{__name__}.MaxClient".
headers (UserAgentPayload) -- Заголовки для подключения к WebSocket.
token (str | None, optional) -- Токен авторизации. Если не передан, будет выполнен процесс логина по номеру телефона.
host (str, optional) -- Хост API сервера.
port (int, optional) -- Порт API сервера.
registration (bool, optional) -- Флаг регистрации нового пользователя.
first_name (str, optional) -- Имя пользователя для регистрации. Требуется, если registration=True.
last_name (str | None, optional) -- Фамилия пользователя для регистрации.
send_fake_telemetry (bool, optional) -- Флаг отправки фейковой телеметрии.
proxy (str | Literal[True] | None, optional) -- Прокси для подключения к WebSocket (см. https://websockets.readthedocs.io/en/stable/topics/proxies.html).
reconnect (bool, optional) -- Флаг автоматического переподключения при потере соединения.

Raises:

InvalidPhoneError -- Если формат номера телефона неверный.

async change_group_profile(chat_id, name, description=None)¶

Изменяет профиль группы

Parameters:

chat_id (int) -- ID группы.
name (str | None) -- Название группы.
description (str | None, optional) -- Описание группы. Defaults to None.

Returns:

None

Return type:

None

async change_group_settings(chat_id, all_can_pin_message=None, only_owner_can_change_icon_title=None, only_admin_can_add_member=None, only_admin_can_call=None, members_can_see_private_link=None)¶

Изменяет настройки группы

Parameters:

chat_id (int) -- ID группы.
all_can_pin_message (bool | None, optional) -- Все могут закреплять сообщения. Defaults to None.
only_owner_can_change_icon_title (bool | None, optional) -- Только владелец может менять иконку и название. Defaults to None.
only_admin_can_add_member (bool | None, optional) -- Только администраторы могут добавлять участников. Defaults to None.
only_admin_can_call (bool | None, optional) -- Только администраторы могут звонить. Defaults to None.
members_can_see_private_link (bool | None, optional) -- Участники могут видеть приватную ссылку. Defaults to None.

Returns:

None

Return type:

None

async change_profile(first_name, last_name=None, description=None, photo=None)¶

Изменяет информацию профиля текущего пользователя.

Parameters:

first_name (str) -- Имя пользователя.
last_name (str | None) -- Фамилия пользователя. По умолчанию None.
description (str | None) -- Описание профиля. По умолчанию None.
photo (Photo | None)

Returns:

True, если профиль успешно изменен.

Return type:

bool

async close()[source]¶

Закрывает клиент и освобождает ресурсы.

Returns:: None
Return type:: None

async close_all_sessions()¶

Закрывает все активные сессии, кроме текущей.

Returns:: True, если операция выполнена успешно.
Return type:: bool

async connect(user_agent=None)¶

Устанавливает соединение WebSocket с сервером и выполняет handshake.

Parameters:: user_agent (UserAgentPayload | None) -- Пользовательский агент для handshake. Если None, используется значение по умолчанию.
Returns:: Результат handshake.
Return type:: dict[str, Any] | None

async create_folder(title, chat_include, filters=None)¶

Создает новую папку для группировки чатов.

Parameters:

title (str) -- Название папки.
chat_include (list[int]) -- Список ID чатов для включения в папку.
filters (list[Any] | None) -- Список фильтров для папки (опциональный параметр).

Returns:

Объект FolderUpdate с информацией о созданной папке.

Return type:

FolderUpdate

async create_group(name, participant_ids=None, notify=True)¶

Создает группу

Parameters:

name (str) -- Название группы.
participant_ids (list[int] | None, optional) -- Список идентификаторов участников. Defaults to None.
notify (bool, optional) -- Флаг оповещения. Defaults to True.

Returns:

Объект Chat и Message или None при ошибке.

Return type:

tuple[Chat, Message] | None

async delete_folder(folder_id)¶

Удаляет папку.

Parameters:: folder_id (str) -- Идентификатор папки для удаления.
Returns:: Объект FolderUpdate с результатом операции или None.
Return type:: FolderUpdate | None

async delete_message(chat_id, message_ids, for_me, use_queue=False)¶

Удаляет одно или несколько сообщений.

Parameters:

chat_id (int) -- Идентификатор чата.
message_ids (list[int]) -- Список идентификаторов сообщений для удаления.
for_me (bool) -- Удалить только для себя (не видимо другим).
use_queue (bool) -- Использовать очередь для отправки.

Returns:

True, если сообщения успешно удалены.

Return type:

bool

async edit_message(chat_id, message_id, text, attachment=None, attachments=None, use_queue=False)¶

Редактирует текст и/или вложения существующего сообщения.

Parameters:

chat_id (int) -- Идентификатор чата.
message_id (int) -- Идентификатор сообщения для редактирования.
text (str) -- Новый текст сообщения.
attachment (Photo | File | Video | None) -- Новое вложение (фото, файл или видео).
attachments (list[Photo | Video | File] | None) -- Список новых множественных вложений.
use_queue (bool) -- Использовать очередь для отправки.

Returns:

Отредактированное сообщение или None.

Return type:

Message | None

Raises:

Error -- Если редактирование не удалось.

async fetch_chats(marker=None)¶

Загружает список чатов

Parameters:: marker (int | None) -- Маркер для пагинации, по умолчанию None
Returns:: Список объектов Chat
Return type:: list[Chat]

async fetch_history(chat_id, from_time=None, forward=0, backward=200)¶

Получает историю сообщений из чата.

Parameters:

chat_id (int) -- Идентификатор чата.
from_time (int | None) -- Временная метка для начала выборки.
forward (int) -- Кол-во сообщений вперед от from_time.
backward (int) -- Кол-во сообщений назад от from_time.

Returns:

Список сообщений или None.

Return type:

list[Message] | None

async fetch_users(user_ids)¶

Загружает информацию о пользователях с сервера.

Запрашивает данные о пользователях по их идентификаторам и добавляет их в внутренний кеш.

Parameters:: user_ids (list[int]) -- Список идентификаторов пользователей для загрузки.
Returns:: Список загруженных объектов User.
Return type:: list[User]

async find_members(chat_id, query)¶

Поиск участников канала по строке Внимание! веб-клиент всегда возвращает только определённое количество пользователей, тоесть пагинация здесь не реализована!

Parameters:

chat_id (int) -- Идентификатор канала
query (str) -- Строка для поиска участников

Returns:

Список участников канала

Return type:

tuple[list[Member], int | None]

get_cached_user(user_id)¶

Получает пользователя из кеша по его идентификатору.

Проверяет внутренний кеш пользователей и возвращает объект User если пользователь был ранее загружен.

Parameters:: user_id (int) -- Идентификатор пользователя.
Returns:: Объект User из кеша или None, если пользователь не найден.
Return type:: User | None

async get_chat(chat_id)¶

Получает информацию о группе по ее ID

Parameters:: chat_id (int) -- Идентификатор группы.
Returns:: Объект Chat.
Return type:: Chat

get_chat_id(first_user_id, second_user_id)¶

Получение айди лс (диалога)

Parameters:

first_user_id (int) -- ID первого пользователя
second_user_id (int) -- ID второго пользователя

Returns:

Айди диалога

Return type:

int

async get_chats(chat_ids)¶

Получает информацию о группах по их ID

Parameters:: chat_ids (list[int]) -- Список идентификаторов групп.
Returns:: Список объектов Chat.
Return type:: list[Chat]

async get_file_by_id(chat_id, message_id, file_id)¶

Получает файл

Parameters:

chat_id (int) -- ID чата
message_id (int) -- ID сообщения
file_id (int) -- ID файла

Returns:

Объект FileRequest или None

Return type:

FileRequest | None

async get_folders(folder_sync=0)¶

Получает список всех папок пользователя.

Parameters:: folder_sync (int) -- Синхронизационный маркер папок. По умолчанию 0.
Returns:: Объект FolderList с информацией о папках.
Return type:: FolderList

async get_reactions(chat_id, message_ids)¶

Получает реакции на сообщения.

Parameters:

chat_id (int) -- ID чата
message_ids (list[str]) -- Список ID сообщений

Returns:

Словарь с ID сообщений и соответствующими реакциями

Return type:

dict[str, ReactionInfo] | None

async get_sessions()¶

Получает информацию о всех активных сессиях пользователя.

Возвращает список всех сессий, в которых авторизован пользователь.

Returns:: Список объектов Session.
Return type:: list[Session]
Raises:: Error -- Если произошла ошибка при получении данных.

async get_user(user_id)¶

Получает информацию о пользователе по его идентификатору.

Метод использует внутренний кеш. Если пользователь уже загружен, возвращает его из кеша, иначе выполняет запрос к серверу.

Parameters:: user_id (int) -- Идентификатор пользователя.
Returns:: Объект User или None, если пользователь не найден.
Return type:: User | None

async get_users(user_ids)¶

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

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

Parameters:: user_ids (list[int]) -- Список идентификаторов пользователей.
Returns:: Список объектов User в порядке, соответствующем входному списку.
Return type:: list[User]

async get_video_by_id(chat_id, message_id, video_id)¶

Получает видео

Parameters:

chat_id (int) -- ID чата
message_id (int) -- ID сообщения
video_id (int) -- ID видео

Returns:

Объект VideoRequest или None

Return type:

VideoRequest | None

async idle()¶

Поддерживает клиента в «ожидающем» состоянии до закрытия клиента или иного прерывающего события.

Returns:: Никогда не возвращает значение; функция блокирует выполнение.
Return type:: None

inspect()¶

Выводит в лог текущий статус клиента для отладки.

Return type:: None

async invite_users_to_channel(chat_id, user_ids, show_history=True)¶

Приглашает пользователей в канал

Parameters:

chat_id (int) -- ID канала.
user_ids (list[int]) -- Список идентификаторов пользователей.
show_history (bool, optional) -- Флаг оповещения. Defaults to True.

Returns:

Объект Chat или None при ошибке.

Return type:

Chat | None

async invite_users_to_group(chat_id, user_ids, show_history=True)¶

Приглашает пользователей в группу

Parameters:

chat_id (int) -- ID группы.
user_ids (list[int]) -- Список идентификаторов пользователей.
show_history (bool, optional) -- Флаг оповещения. Defaults to True.

Returns:

Объект Chat или None при ошибке.

Return type:

Chat | None

async join_channel(link)¶

Присоединяется к каналу по ссылке

Parameters:: link (str) -- Ссылка на канал
Returns:: Объект канала, если присоединение прошло успешно, иначе None
Return type:: Channel | None

async join_group(link)¶

Вступает в группу по ссылке

Parameters:: link (str) -- Ссылка на группу.
Returns:: Объект чата группы
Return type:: Chat

async leave_channel(chat_id)¶

Покидает канал

Parameters:: chat_id (int) -- Идентификатор канала.
Returns:: None
Return type:: None

async leave_group(chat_id)¶

Покидает группу

Parameters:: chat_id (int) -- Идентификатор группы.
Returns:: None
Return type:: None

async load_members(chat_id, marker=0, count=50)¶

Загружает членов канала

Parameters:

chat_id (int) -- Идентификатор канала
marker (int | None) -- Маркер для пагинации. По умолчанию DEFAULT_MARKER_VALUE
count (int) -- Количество членов для загрузки. По умолчанию DEFAULT_CHAT_MEMBERS_LIMIT.

Returns:

Список участников канала и маркер для следующей страницы

Return type:

tuple[list[Member], int | None]

async login_with_code(temp_token, code, start=False)[source]¶

Завершает кастомный login flow: отправляет код, сохраняет токен и запускает пост-логин задачи.

Parameters:

temp_token (str) -- Временный токен, полученный из request_code.
code (str) -- Код верификации (6 цифр).
start (bool, optional) -- Флаг запуска пост-логин задач и ожидания навсегда. Если False, только сохраняет токен.

Returns:

None

Return type:

None

async logout()¶

Выполняет выход из текущей сессии.

Returns:: True, если выход выполнен успешно.
Return type:: bool

on_chat_update(handler)¶

Устанавливает обработчик обновления информации о чате.

Parameters:: handler (Callable[[Chat], Any | Awaitable[Any]]) -- Функция или coroutine с аргументом (chat: Chat).
Returns:: Установленный обработчик.
Return type:: Callable[[Chat], Any | Awaitable[Any]]

on_message(filter=None)¶

Декоратор для регистрации обработчика входящих сообщений.

Позволяет установить функцию-обработчик для всех входящих сообщений или только для сообщений, соответствующих заданному фильтру.

Parameters:: filter (BaseFilter[Message] | None) -- Фильтр для обработки сообщений. По умолчанию None.
Returns:: Декоратор для функции-обработчика.
Return type:: Callable

Example:

@client.on_message(Filter.text("hello"))
async def handle_hello(message: Message):
    await client.send_message(
        chat_id=message.chat_id,
        text="Hello!"
    )

on_message_delete(filter=None)¶

Декоратор для установки обработчика удаленных сообщений.

Parameters:: filter (BaseFilter[Message] | None) -- Фильтр для обработки сообщений. По умолчанию None.
Returns:: Декоратор для функции-обработчика.
Return type:: Callable

on_message_edit(filter=None)¶

Декоратор для установки обработчика отредактированных сообщений.

Parameters:: filter (BaseFilter[Message] | None) -- Фильтр для обработки сообщений. По умолчанию None.
Returns:: Декоратор для функции-обработчика.
Return type:: Callable

on_raw_receive(handler)¶

Устанавливает обработчик для получения необработанных данных от сервера.

Parameters:: handler (Callable[[dict[str, Any]], Any | Awaitable[Any]]) -- Функция или coroutine с аргументом (data: dict).
Returns:: Установленный обработчик.
Return type:: Callable[[dict[str, Any]], Any | Awaitable[Any]]

on_reaction_change(handler)¶

Устанавливает обработчик изменения реакций на сообщения.

Parameters:: handler (Callable[[str, int, ReactionInfo], Any | Awaitable[Any]]) -- Функция или coroutine с аргументами (message_id: str, chat_id: int, reaction_info: ReactionInfo).
Returns:: Установленный обработчик.
Return type:: Callable[[str, int, ReactionInfo], Any | Awaitable[Any]]

on_start(handler)¶

Устанавливает обработчик, вызываемый при старте клиента.

Parameters:: handler (Callable[[], Any | Awaitable[Any]]) -- Функция или coroutine без аргументов.
Returns:: Установленный обработчик.
Return type:: Callable[[], Any | Awaitable[Any]]

async pin_message(chat_id, message_id, notify_pin)¶

Закрепляет сообщение в чате.

Parameters:

chat_id (int) -- Идентификатор чата.
message_id (int) -- Идентификатор сообщения.
notify_pin (bool) -- Отправить уведомление о закреплении.

Returns:

True, если сообщение успешно закреплено.

Return type:

bool

async read_message(message_id, chat_id)¶

Отмечает сообщение как прочитанное.

Parameters:

message_id (int) -- ID сообщения
chat_id (int) -- ID чата

Returns:

Объект ReadState

Return type:

ReadState

async remove_contact(contact_id)¶

Удаляет контакт из списка контактов

Parameters:: contact_id (int) -- ID контакта
Returns:: True если успешно
Return type:: Literal[True]
Raises:: ResponseStructureError -- Если структура ответа неверна

async remove_reaction(chat_id, message_id)¶

Удаляет реакцию с сообщения.

Parameters:

chat_id (int) -- ID чата
message_id (str) -- ID сообщения

Returns:

Объект ReactionInfo или None

Return type:

ReactionInfo | None

async remove_users_from_group(chat_id, user_ids, clean_msg_period)¶

Удаляет пользователей из группы

Parameters:

chat_id (int) -- ID группы.
user_ids (list[int]) -- Список идентификаторов пользователей.
clean_msg_period (int) -- Период очистки сообщений.

Returns:

True, если удаление прошло успешно, иначе False.

Return type:

bool

async request_code(phone, language='ru')¶

Запрашивает код аутентификации для указанного номера телефона и возвращает временный токен.

Метод отправляет запрос на получение кода верификации на переданный номер телефона. Используется в процессе аутентификации или регистрации.

Parameters:

phone (str) -- Номер телефона в международном формате.
language (str) -- Язык для сообщения с кодом. По умолчанию "ru".

Returns:

Временный токен для дальнейшей аутентификации.

Return type:

str

Raises:

ValueError -- Если полученные данные имеют неверный формат.
Error -- Если сервер вернул ошибку.

Note

Используется только в пользовательском flow аутентификации.

async resend_code(phone, language='ru')¶

Повторно запрашивает код аутентификации для указанного номера телефона и возвращает временный токен.

Parameters:

phone (str) -- Номер телефона в международном формате.
language (str) -- Язык для сообщения с кодом. По умолчанию "ru".

Returns:

Временный токен для дальнейшей аутентификации.

Return type:

str

Raises:

ValueError -- Если полученные данные имеют неверный формат.
Error -- Если сервер вернул ошибку.

async resolve_channel_by_name(name)¶

Получает информацию о канале по его имени

Parameters:: name (str) -- Имя канала
Returns:: Объект Channel или None, если канал не найден
Return type:: Channel | None

async resolve_group_by_link(link)¶

Разрешает группу по ссылке

Parameters:: link (str) -- Ссылка на группу.
Returns:: Объект чата группы или None, если не найдено.
Return type:: Chat | None

async rework_invite_link(chat_id)¶

Пересоздает ссылку для приглашения в группу

Parameters:: chat_id (int) -- ID группы.
Returns:: Обновленный объект чата с новой ссылкой.
Return type:: Chat

async search_by_phone(phone)¶

Выполняет поиск пользователя по номеру телефона.

Parameters:: phone (str) -- Номер телефона пользователя.
Returns:: Объект User с найденными данными пользователя.
Return type:: User
Raises:: Error -- Если пользователь не найден или произошла ошибка.

async send_message(text, chat_id, notify=True, attachment=None, attachments=None, reply_to=None, use_queue=False)¶

Отправляет текстовое сообщение в чат с опциональными вложениями.

Parameters:

text (str) -- Текст сообщения.
chat_id (int) -- Идентификатор чата, в который отправляется сообщение.
notify (bool) -- Флаг оповещения о новом сообщении. По умолчанию True.
attachment (Photo | File | Video | None) -- Одно вложение (фото, файл или видео).
attachments (list[Photo | File | Video] | None) -- Список множественных вложений.
reply_to (int | None) -- Идентификатор сообщения для ответа.
use_queue (bool) -- Использовать очередь для отправки. По умолчанию False.

Returns:

Объект сообщения или None, если используется очередь.

Return type:

Message | None

Raises:

Error -- Если загрузка вложения или отправка сообщения не удалась.

async set_password(password, email=None, hint=<pymax.static.constant._Unset object>)¶

Устанавливает пароль для аккаунта

Warning

Метод не будет работать, если на аккаунте уже установлен пароль.

Parameters:

password (str) -- Новый пароль для аккаунта.
email (str) -- Адрес электронной почты для восстановления пароля.
hint (str | None) -- Подсказка для пароля. По умолчанию None.

Returns:

None

Return type:

None

async start()[source]¶

Запускает клиент, подключается к WebSocket, авторизует пользователя (если нужно) и запускает фоновый цикл. Теперь включает безопасный reconnect-loop, если self.reconnect=True.

Returns:: None
Return type:: None

task(seconds, minutes=0, hours=0)¶

Декоратор для планирования периодической задачи.

Parameters:

seconds (float) -- Интервал выполнения в секундах.
minutes (float) -- Интервал выполнения в минутах. По умолчанию 0.
hours (float) -- Интервал выполнения в часах. По умолчанию 0.

Returns:

Декоратор для функции-обработчика.

Return type:

Callable[[], Any | Awaitable[Any]]

Example:

@client.task(seconds=10)
async def task():
    await client.send_message(chat_id=123, text="Hello!")

async update_folder(folder_id, title, chat_include=None, filters=None, options=None)¶

Обновляет параметры существующей папки.

Parameters:

folder_id (str) -- Идентификатор папки.
title (str) -- Название папки.
chat_include (list[int] | None) -- Список ID чатов для включения в папку.
filters (list[Any] | None) -- Список фильтров для папки.
options (list[Any] | None) -- Список опций для папки.

Returns:

Объект FolderUpdate с результатом или None.

Return type:

FolderUpdate | None

property ws: ClientConnection¶

SocketMaxClient¶

Асинхронный TCP Socket клиент для взаимодействия с Max API. Используется для входа и регистрации по номеру телефона.

Поддерживаемые методы авторизации:

✅ Вход по номеру телефона (DESKTOP, ANDROID, IOS device_types)
✅ Регистрация нового пользователя по номеру телефона

Когда использовать SocketMaxClient:

Необходимо зарегистрировать новых пользователей
Требуется вход по номеру телефона (без QR-кода)
Необходимо использовать DESKTOP, ANDROID или IOS device_types
Разрабатываете системы массовой регистрации или авторизации
Нужна автоматизация входа (вход по номеру телефона удобнее для автоматизации, чем сканирование QR-кода)

Note

SocketMaxClient — это полноценный и рекомендуемый способ авторизации!

Не воспринимайте Socket клиент как что-то вспомогательное или альтернативное. Вход по номеру телефона — это основной способ авторизации в Max, и SocketMaxClient обеспечивает надежный доступ к этому функционалу.

Для многих сценариев (особенно для автоматизации и интеграции) вход по номеру телефона удобнее и практичнее, чем сканирование QR-кода.

Инициализация и вход:

from pymax import SocketMaxClient
from pymax.payloads import UserAgentPayload

# Для входа по номеру телефона
client = SocketMaxClient(
    phone="+79001234567",
    work_dir="./cache",
    headers=UserAgentPayload(device_type="DESKTOP"),
)

await client.start()  # Потребуется ввести код подтверждения

Регистрация нового пользователя:

from pymax import SocketMaxClient
from pymax.payloads import UserAgentPayload

client = SocketMaxClient(
    phone="+79001234567",
    registration=True,                      # Флаг регистрации
    first_name="Иван",
    last_name="Петров",
    headers=UserAgentPayload(device_type="DESKTOP"),
)

await client.start()  # Потребуется ввести код подтверждения

Important

SocketMaxClient должен использоваться для:

Регистрации новых пользователей — MaxClient не поддерживает регистрацию
Входа по номеру телефона — требуется phone verification код
Системной авторизации — когда QR-код недоступен или неудобен
Автоматизации — вход по номеру телефона легче автоматизировать

Note

После успешной авторизации через SocketMaxClient вы можете сохранить токен и использовать его с MaxClient для более быстрого подключения к WebSocket API.

# Первый раз: получаем токен через Socket
socket_client = SocketMaxClient(phone="+79001234567")
await socket_client.start()
token = socket_client.token

# Сохраняем токен

# Следующие разы: используем токен с WebSocket клиентом
ws_client = MaxClient(phone="+79001234567", token=token)
await ws_client.start()