MAX Bot API: Мои первые шаги в разработке ботов

Информация о материале: Автор: Геннадий Едиг; Категория: Администрирование и Вайб-кодинг; Опубликовано: 19 июля 2026; Просмотров: 4

В этой статье я собрал все ключевые возможности MAX Bot API, которые мы открыли и протестировали в процессе разработки ботов для платформы MAX. Статья построена на реальном опыте и содержит рабочие примеры кода на Python.

Базовые принципы работы с API

Все запросы к MAX Bot API направляются на домен https://platform-api2.max.ru. Авторизация выполняется через заголовок Authorization: <токен_бота> — передача токена через query-параметры больше не поддерживается.

Важно: До 19 июля 2026 необходимо перенаправить запросы с platform-api.max.ru на platform-api2.max.ru.

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

1. Отправка сообщений

Метод POST /messages позволяет отправлять сообщения в чаты и личные диалоги.

Ключевые параметры:

user_id или chat_id — указывается в query-строке
text — текст сообщения (до 4000 символов)
attachments — вложения (кнопки, медиафайлы)
format — форматирование текста (markdown или html)

Пример отправки сообщения на Python:

async def send_message_via_api(chat_id, message_text, bot_token):
    url = f"https://platform-api2.max.ru/messages?chat_id={chat_id}"
    headers = {
        "Authorization": bot_token,
        "Content-Type": "application/json"
    }
    payload = {"text": message_text}
    
    async with aiohttp.ClientSession() as session:
        async with session.post(url, json=payload, headers=headers) as response:
            return response.status == 200

2. Получение сообщений из канала

Метод GET /messages возвращает сообщения из чата или канала.

Параметры:

chat_id — ID канала (обязательно, если не указан message_ids)
count — количество сообщений (до 100)
from — временная метка для пагинации

Важная особенность: Сообщения возвращаются в обратном порядке — самые новые первыми.

Пример получения постов с пагинацией:

async def get_channel_posts(chat_id, count=100, from_time=None):
    headers = {"Authorization": BOT_TOKEN}
    params = {"chat_id": chat_id, "count": count}
    if from_time:
        params["from"] = from_time
    
    async with aiohttp.ClientSession() as session:
        async with session.get(API_URL, headers=headers, params=params) as response:
            data = await response.json()
            return data.get("messages", [])

3. Управление администраторами канала

Назначение прав администратора

Метод POST /chats/{chatId}/members/admins — бот должен сам быть администратором с правом add_admins.

Доступные права:

read_all_messages — чтение всех сообщений (обязательно для работы с сообщениями)
write — создание постов в каналах (также даёт редактирование и удаление)
edit — редактирование постов
delete — удаление постов
pin_message — закрепление сообщений
add_remove_members — управление участниками
add_admins — управление администраторами
change_chat_info — изменение информации о канале

Важно: Право write автоматически даёт edit и delete. Отдельного права "только создавать посты" не существует.

Пример выдачи прав:

async def grant_admin_rights(chat_id, user_id, bot_token):
    url = f"{API_URL}/chats/{chat_id}/members/admins"
    headers = {
        "Authorization": bot_token,
        "Content-Type": "application/json"
    }
    payload = {
        "admins": [
            {
                "user_id": user_id,
                "permissions": [
                    "read_all_messages",
                    "write"
                ]
            }
        ]
    }
    
    async with aiohttp.ClientSession() as session:
        async with session.post(url, json=payload, headers=headers) as response:
            return response.status == 200

Получение списка администраторов

Метод GET /chats/{chatId}/members/admins — возвращает всех администраторов канала.

Пример:

async def get_chat_admins(chat_id):
    url = f"{API_URL}/chats/{chat_id}/members/admins"
    headers = {"Authorization": BOT_TOKEN}
    
    async with aiohttp.ClientSession() as session:
        async with session.get(url, headers=headers) as response:
            data = await response.json()
            return data.get("members", [])

Отзыв прав администратора

Метод DELETE /chats/{chatId}/members/admins/{userId}.

async def revoke_admin_rights(chat_id, user_id):
    url = f"{API_URL}/chats/{chat_id}/members/admins/{user_id}"
    headers = {"Authorization": BOT_TOKEN}
    
    async with aiohttp.ClientSession() as session:
        async with session.delete(url, headers=headers) as response:
            return response.status == 200

4. Проверка участников канала

Метод GET /chats/{chatId}/members?user_ids={userId} — позволяет проверить, подписан ли пользователь на канал.

async def check_user_subscription(chat_id, user_id):
    endpoint = f"/chats/{chat_id}/members?user_ids={user_id}"
    url = f"{API_URL}{endpoint}"
    headers = {"Authorization": BOT_TOKEN}
    
    async with aiohttp.ClientSession() as session:
        async with session.get(url, headers=headers) as response:
            data = await response.json()
            members = data.get("members", [])
            return bool(members) and members[0].get("status") in ["member", "administrator", "creator"]

Получение событий в реальном времени

API поддерживает два способа получения событий:

Webhook (рекомендуется для production)

Метод POST /subscriptions настраивает доставку событий на ваш HTTPS-сервер.

Требования:

HTTPS на порту 443
Сертификат от доверенного CA
Ответ HTTP 200 в течение 30 секунд

Пример настройки:

curl -X POST "https://platform-api2.max.ru/subscriptions" \
  -H "Authorization: {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/webhook",
    "update_types": ["message_created", "bot_started"],
    "secret": "your_secret"
  }'

Long Polling (только для разработки)

Метод GET /updates — подходит для тестирования, но не для production из-за ограничений.

Архитектура ботов из нашего проекта

Мы разработали два независимых скрипта для разных задач:

1. check_bot.py — архивация постов канала

Функционал:

Синхронизация при старте: проверяет все посты в канале и добавляет недостающие в БД
Слушает канал через long polling и сохраняет новые посты

Ключевые функции:

sync_posts() — синхронизация с пагинацией через параметр from
save_channel_post() — сохранение в MySQL

2. echo_bot.py — диалоговый бот с управлением правами

Команды для всех пользователей:

/status — проверка статуса подписки
/admin — запрос прав администратора канала

Админ-команды:

/admin_add <user_id> <user_name> — добавить администратора бота
/admin_remove <user_id> — удалить администратора бота
/admin_revoke <user_id> — отозвать права администратора канала
/admin_list — список администраторов бота
/admin_users — список всех пользователей

Система уведомлений: Все важные события отправляются администраторам бота через API.

Получение chat_id

Chat ID можно получить только через события:

Webhook: в объекте Update
Long Polling: в объекте Update

Типичные ошибки и их решения

"Chat not found" при отправке сообщения

Администратор должен первым написать боту — бот не может инициировать диалог.

"proto.payload" и "errors.required"

Проблема в структуре запроса. Проверьте, что chat_id передаётся в параметрах URL, а не в теле.

"Can't set message modify permission without read_all_messages"

Права, связанные с сообщениями, требуют read_all_messages.

"permission.denied" при выдаче прав

У бота нет права add_admins — проверьте через GET /chats/{chatId}/members/admins.