Запрос функциональности: нативная поддержка аудио и видеокружков в maxapi-python

[dabankrot]

Библиотека: maxapi-python 2.3.1
Дата: 2026-07-09
Контекст: Продакшн-использование в коннекторе Bitrix24 Open Line (max-connector), который пересылает медиа между CRM Bitrix и мессенджером MAX.

---

Краткое описание

maxapi-python 2.3.1 не умеет отправлять и принимать аудиосообщения (войсы) и видеокружки. Сейчас это работает через 10+ monkey-patch'ей во время выполнения. Ниже — список проблем для нативного исправления в библиотеке.

---

1. UploadPayload — нет поля type

Проблема: UploadPayload содержит только поля count и profile. Сервер MAX в opcode VIDEO_UPLOAD (135) принимает параметр type для выбора типа загрузки:

type	Значение	Примечание
0	Обычное видео	Текущее поведение по умолчанию
1	Видеокружок	VIDEO_MESSAGE
2	Аудио	Голосовое сообщение
3	Сторис	(не тестировалось)

Запрос: Добавить поле type: int = 0 в UploadPayload и прокидывать его в upload_video() / upload_file().

---

2. upload_video() — нет параметра type

Проблема: UploadService.upload_video() отправляет VIDEO_UPLOAD без type, сервер всегда обрабатывает как обычное видео (type=0). Видеокружки (type=1) отправить нельзя.

Запрос: Добавить параметр type (или video_type) в upload_video(), чтобы вызов мог указать type=1 для кружков.

---

3. Загрузка аудио — нет нативной поддержки

Проблема: Нет класса AudioFile и нет способа загрузить аудио как войс. File грузится через FILE_UPLOAD, но MAX ожидает аудио через VIDEO_UPLOAD с type=2. Сервер возвращает audioId + token, а исходящее сообщение требует audio-специфичный payload.

Запрос:

• Добавить класс AudioFile (аналог File / Video).
• Маршрутизировать аудио через VIDEO_UPLOAD с type=2.
• Добавить AttachAudioPayload с полями: _type=AUDIO, audioId, token, duration, wave.
• Зарегистрировать AttachAudioPayload в SendMessagePayloadMessage.attaches, EditMessagePayload.attachments, ForwardMessagePayloadMessage.attaches через Union.

---

4. VideoUploadSignal — не принимает audioId

Проблема: При загрузке аудио (type=2) сервер шлёт NOTIF_ATTACH (opcode 136) с audioId вместо videoId. VideoUploadSignal принимает только videoId — событие завершения загрузки молча игнорируется, future никогда не резолвится.

Текущий воркэраунд: Патч validation_alias на AliasChoices("videoId", "audioId").

Запрос: Добавить audioId как принимаемый алиас для video_id в VideoUploadSignal, либо создать отдельную модель AudioUploadSignal.

---

5. resolve_attach — игнорирует события аудио-загрузки

Проблема: resolve_attach() валидирует VideoUploadSignal (ожидает videoId). Для аудио сервер шлёт audioId — валидация падает, событие игнорируется. Future загрузки никогда не завершается, возникает таймаут.

Запрос: resolve_attach должен обрабатывать audioId-payload'ы и возвращать VIDEO_READY (или новый тип события AUDIO_READY).

---

6. VideoRequest — поле cache обязательно, но сервер его не присылает

Проблема: client.get_video_by_id() возвращает модель VideoRequest с обязательным полем cache. Сервер иногда возвращает {'MP4_480': 'https://...'} без cache — ValidationError. Воспроизводится при скачивании видеокружков.

Запрос: Сделать cache опциональным в VideoRequest, либо обрабатывать случай, когда сервер возвращает URL напрямую в ключах без обёртки cache.

---

7. Класс Video — нет поля type для отличия кружка от обычного видео

Проблема: Video не имеет поля type для различения обычного видео и кружка. Сервер использует video_type=1 для кружков в VideoAttachment.

Запрос: Добавить поле video_type (или type) в Video и VideoAttachment со значениями:

• 0 — обычное видео
• 1 — видеокружок (VIDEO_MESSAGE)

---

8. read_message — отметка сообщений прочитанными

Проблема: Нет публичного метода для отметки входящих сообщений как прочитанных. Мы вызываем client.read_message(), который существует, но не задокументирован.

Запрос: Официально expose'нуть и задокументировать read_message(message_id, chat_id) как публичный метод API.

---

9. Устойчивость сессий — обработка FAIL_LOGOUT_ALL

Проблема: Когда сервер MAX инвалидирует все сессии аккаунта (ошибка login.token / FAIL_LOGOUT_ALL), Client.start() выбрасывает исключение, аккаунт остаётся отключённым. Нет callback'а или события для этого состояния — коннектор не может отличить «временная сетевая ошибка» от «сессия навсегда инвалидирована, нужен re-pairing по SMS».

Запрос: Предоставить структурированное событие или исключение для FAIL_LOGOUT_ALL, чтобы коннекторы могли запустить re-pairing (SMS-флоу) вместо слепых ретраев с мёртвым токеном.

---

Приоритеты

#	Проблема	Критичность	Влияние
1	UploadPayload без type	Высокая	Блокирует отправку аудио+кружков
2	upload_video без type	Высокая	Блокирует отправку кружков
3	Нет загрузки аудио	Высокая	Блокирует отправку аудио
4	VideoUploadSignal audioId	Высокая	Загрузка аудио не завершается
5	resolve_attach игнорирует аудио	Высокая	Загрузка аудио не завершается
6	VideoRequest cache обязательно	Средняя	Скачивание кружков падает
7	Video без type	Низкая	Нельзя отличить кружок/обычное
8	read_message не задокументирован	Низкая	Нет публичного API для read-receipts
9	FAIL_LOGOUT_ALL обработка	Средняя	Молчаливая инвалидация сессии

---

Окружение

• maxapi-python: 2.3.1
• Python: 3.12
• Сервер MAX: api.oneme.ru

[ink-developer]

Кружки и голосовые по плану в 2.4.0

Документация к read_message есть - https://docs.pymax.org/api/client-client.html#pymax.Client.read_message

FAIL_LOGOUT_ALL можно ловить через on_error, пример даже был где то в чате

[dabankrot]

Кружки и голосовые по плану в 2.4.0

Документация к read_message есть - https://docs.pymax.org/api/client-client.html#pymax.Client.read_message

FAIL_LOGOUT_ALL можно ловить через on_error, пример даже был где то в чате

Привет! Спасибо за ответ — по кружкам/голосу (2.4.0), read_message и on_error понятно. Заодно докопался до причины наших принудительных разлогинов, хочу уточнить пару вещей.

В тесте 3 номера как долгоживущие userbot'ы (заводим сообщения в открытые линии Bitrix). Сегодня 2 из 3 сервер принудительно разлогинил — прилетел LOGOUT (opcode 20), при реконнекте login.token, пришлось перепривязывать по SMS. Третий номер, который с утра не трогали, живёт спокойно.

Вопросы:

1. Верно ли, что принудительный logout (opcode 20 / у вас FAIL_LOGOUT_ALL) в норме прилетает именно на новый логин того же аккаунта? Если держать одну сессию и не логиниться заново, пока она жива, — аккаунт живёт сколь угодно долго?
2. Насколько критично сохранять один и тот же device_id (и session .db) между рестартами? Смена device_id считается «новым устройством» и дропает старую сессию? Что посоветуете для стабильной долгой сессии — беречь .db или явно фиксировать device_id/mt_instance_id в ExtraConfig?
3. Заметили: живой серверный LOGOUT (opcode 20) в on_error не приходит — только в on_raw (on_error ловит login.token лишь на старте). Это ожидаемо? on_raw — правильный способ отследить принудительный разлогин живой сессии? Не планируете отдельное событие (on_logout/on_session_terminated)?
4. При обрыве сети встроенный reconnect переиспользует сохранённый токен без нового интерактивного логина (т.е. не триггерит drop-old-session)? Как правильно, чтобы сетевой сбой не превратился в само-разлогин?
5. Сервер иногда шлёт RECONNECT (opcode 3) — pymax его обрабатывает, или ловить самим и переподключаться?
6. Токен приходит с TTL (tokenTtl) — pymax сам обновляет/ротирует токен по ходу, или это на нашей стороне?

Спасибо!

[ink-developer]

1. В теории да
2. За смену device_id сессия не отлетит сразу но лучше хранить один и тот же
3. LOGOUT (20) это опкод для разлогина. (client.logout). это не ошибка а стандартное действие, по этому оно и не попадает в on_error
4. да, реконнект просто перезапускает клиент. если сессия есть в бд то он будет использовать ее (если только не передан токен в параметрах клиента)
5. Не слышал о таком, изучу вопрос. Паймакс никак его не обрабатывает
6. Откуда такая информация, не факт что у токена есть ttl. но в любом случае паймакс обновляет токен только если пришел новый после LOGIN (19) или после SESSIONS_CLOSE (97)

[dabankrot]

Ещё не хватило функционала в либе, добавил настройки приватности:

Значения: ALL (все) / CONTACTS (только контакты) / NONE (никто; NOBODY тоже принимается на чтение, но приложение шлёт именно NONE).

Точный кадр для «всем»:
opcode 22 (CONFIG)
payload: {"settings": {"user": {"CHATS_INVITE":"ALL", "SEARCH_BY_PHONE":"ALL", "INCOMING_CALL":"ALL"}}}
(шлём только те ключи, что меняем — сервер мержит; в ответ g64.b эхом отдаёт обновлённые настройки — по нему проверяем, что применилось.)

[ink-developer]

Хорошо, учту