Max Messenger API — обёртка на Python

Возможности

• Двойная аутентификация: поддержка как токен-ориентированной аутентификации для уже существующих сессий, так и верификации по номеру телефона для новых сессий.
• Обработка событий в реальном времени: позволяет задавать пользовательские функции-обработчики для событий, приходящих от сервера (например, новых сообщений или обновлений статуса собеседника).
• Автоматическое восстановление соединения: автоматически переподключается и повторно аутентифицирует сессию в случае обрыва соединения, обеспечивая надёжность работы.
• Вспомогательные методы: содержит удобные методы для выполнения типичных действий — получение истории чата, загрузка файлов и видео, управление контактами и т.д.

Установка

Установите библиотеку с помощью pip:

pip install MaxBridge

Использование

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

Для начала работы создайте экземпляр класса MaxAPI. Вы можете аутентифицироваться с помощью уже имеющегося токена или пройти верификацию по номеру телефона.

С использованием токена аутентификации:

Если у вас уже есть действительный auth_token, вы можете передать его при инициализации для быстрого подключения.

from max_api import MaxAPI

AUTH_TOKEN = "ваш_токен_аутентификации"

api = MaxAPI(auth_token=AUTH_TOKEN)

Как получить токен аутентификации

1. Откройте веб-браузер и перейдите на веб-версию Max Messenger.
2. Войдите в свой аккаунт Max, если вы ещё не авторизованы.
3. После входа откройте инструменты разработчика в браузере (щёлкните правой кнопкой мыши на странице и выберите «Просмотреть код» или нажмите F12).
4. Перейдите на вкладку «Application» («Приложение») в инструментах разработчика.
5. В левой панели в разделе «Storage» («Хранилище») найдите и откройте «Local Storage», затем выберите домен https://web.max.ru.
6. Найдите токен аутентификации — это значение ключа __oneme_auth.
7. Скопируйте значение этого токена. Оно понадобится вам для аутентификации в классе MaxAPI.

Без токена аутентификации (верификация по номеру телефона):

Если у вас нет auth_token, вы можете пройти аутентификацию (войти), подтвердив номер телефона.

from max_api import MaxAPI

api = MaxAPI()

phone_number = "ваш_номер_телефона"  # например, "+79123456789"
api.send_verify_code(phone_number)

# Введите код, полученный по SMS
code = input("Введите код подтверждения: ")
api.check_verify_code(code)

Отправка сообщения

После успешной аутентификации вы можете легко отправлять сообщения в любой чат.

# ID чата, в который нужно отправить сообщение
chat_id = "some_chat_id"
# Текст сообщения
message_text = "Привет из API!"

# Отправка сообщения
api.send_message(chat_id, message_text)

Также можно отправить ответ на конкретное сообщение:

api.send_message(chat_id, "Это ответ.", reply_id="id_сообщения_для_ответа")

Получение событий

Вы можете обрабатывать события в реальном времени (например, новые сообщения), передав функцию-обработчик в параметр on_event при инициализации.

import json

def my_event_handler(event_data):
    """
    Пользовательская функция для обработки входящих событий от сервера.
    """
    opcode = event_data.get("opcode")
    if opcode == 128:  # Событие: новое сообщение
        print(f"Получено новое сообщение: {json.dumps(event_data, indent=2, ensure_ascii=False)}")
    else:
        print(f"Событие от сервера (Opcode {opcode}): {json.dumps(event_data, indent=2, ensure_ascii=False)}")

# Инициализация API с пользовательским обработчиком событий
api = MaxAPI(auth_token=AUTH_TOKEN, on_event=my_event_handler)

# Теперь API будет использовать my_event_handler для обработки входящих событий.
# Не забудьте оставить скрипт запущенным, чтобы получать события.

Получение истории чата

Историю сообщений любого чата можно получить простым вызовом метода.

# ID чата, из которого нужно получить историю
chat_id = "some_chat_id"
# Количество сообщений для получения
message_count = 50

# Получение истории чата
history = api.get_history(chat_id, count=message_count)
print(history)

Подписка на чат

Чтобы получать обновления в реальном времени для конкретного чата (новые сообщения, индикаторы набора текста и т.д.), необходимо подписаться на него.

# ID чата для подписки
chat_id = "some_chat_id"

# Подписка на чат
api.subscribe_to_chat(chat_id)

Завершение работы

API автоматически обрабатывает сигналы SIGINT (Ctrl+C) и SIGTERM. Также вы можете вручную вызвать метод close(), чтобы отключиться от WebSocket-сервера.

api.close()

Справочник API

MaxAPI(auth_token=None, on_event=None)

• auth_token (str, необязательный): токен аутентификации для сессии.
• on_event (callable, необязательный): функция-обработчик событий от сервера. Принимает один аргумент — словарь с данными события.

Методы

• send_message(chat_id, text, reply_id=None, wait_for_response=False, format=False): отправляет сообщение в чат.
• get_history(chat_id, count=30, from_timestamp=None): получает историю сообщений чата.
• subscribe_to_chat(chat_id, subscribe=True): подписывается на обновления чата или отписывается от них.
• mark_as_read(chat_id, message_id): помечает конкретное сообщение как прочитанное.
• get_contact_details(contact_ids): получает информацию о профиле одного или нескольких контактов.
• get_contact_by_phone(phone_number): находит контакт по номеру телефона.
• get_chat_by_id(chat_id): возвращает чат из локального кэша по его ID.
• get_all_chats(): возвращает словарь всех закэшированных чатов.
• send_verify_code(phone_number): отправляет код подтверждения на указанный номер телефона для начала аутентификации.
• check_verify_code(code): проверяет код, полученный по SMS, и завершает аутентификацию.
• send_generic_command(command_name, payload, wait_for_response=True, timeout=10): отправляет произвольную команду API по её строковому имени (например, 'GET_HISTORY').
• get_video(id): скачивает видео по его ID и возвращает как байтовый поток.
• get_file(id, chat_id, msg_id): скачивает файл по его ID и возвращает его содержимое и имя.
• close(): отключается от WebSocket-сервера и завершает работу цикла событий.