Как сделать бота в MAX на Python: первая команда и ответ пользователю

MAX Bot API можно освоить на одном небольшом проекте, если сразу видеть вход, действие и результат. MAX Bot API принимает обычные HTTP-запросы, поэтому первого бота можно собрать на Python без тяжёлого фреймворка. Ниже вы соберёте работающий пример и проверите обычный и граничный сценарии.

Токен легко случайно положить в код, marker легко потерять, а long polling ошибочно принять за готовую production-архитектуру. Поэтому отделим настройку, входные данные, основное действие и проверку. В этой статье вы соберёте бота, который получает новые события, узнаёт команду /start и отправляет ответ в тот же чат. Проверка: сообщение /start даёт один ответ, marker обновляется, а пустая очередь не вызывает ошибку.

Как устроен учебный проект MAX Bot API

MAX Bot API получает входные данные, проверяет их, выполняет одно внешнее действие и сохраняет наблюдаемый результат. Держите ввод, логику и отображение раздельно: тогда каждый этап можно проверить отдельно.

Контрольные точки: токен, события, команда и ответ. Следующий шаг начинается после совпадения с ожидаемым результатом.

От входных данных до видимого результата. Сначала проверяется вход, затем действие и только потом интерфейс.

Собираем рабочий пример шаг за шагом

Материал сверялся с официальной документацией сервиса 21 октября 2026 года. Создайте окружение, установите httpx и задайте MAX_TOKEN. Для разработки используйте long polling, а для production планируйте webhook. Проверьте текущую папку через pwd или Get-Location. Вставьте пример целиком, выполните один раз, затем разбирайте по частям.

import os
import time
import httpx

BASE = "https://platform-api2.max.ru"
TOKEN = os.environ["MAX_TOKEN"]
HEADERS = {"Authorization": TOKEN}

def send(chat_id: int, text: str) -> None:
    response = httpx.post(
        f"{BASE}/messages",
        params={"chat_id": chat_id},
        headers=HEADERS,
        json={"text": text},
        timeout=20,
    )
    response.raise_for_status()

def run() -> None:
    marker = None
    while True:
        response = httpx.get(
            f"{BASE}/updates",
            params={"timeout": 30, "marker": marker},
            headers=HEADERS,
            timeout=40,
        )
        response.raise_for_status()
        payload = response.json()
        marker = payload.get("marker", marker)
        for update in payload.get("updates", []):
            message = update.get("message", {})
            if message.get("body", {}).get("text") == "/start":
                send(message["recipient"]["chat_id"], "Привет! Я бот Кодика.")
        time.sleep(0.2)

if __name__ == "__main__":
    run()

Главная функция принимает явные аргументы и возвращает данные, которые можно проверить отдельно от интерфейса. Найдите в примере вход, проверку и место формирования результата.

Что отличает устойчивый проект от случайного запуска. Явные границы делают ошибку локальной и понятной.

Что происходит внутри и почему это работает

Long polling удерживает запрос до появления события или тайм-аута. Поле marker не даёт повторно читать уже обработанную часть очереди. Логику держите отдельно от вывода: функция получает аргумент и возвращает значение, а интерфейс показывает его. Документация MAX прямо относит GET /updates к разработке и тестированию. Для production нужен webhook и проверяемый HTTPS-адрес.

Marker следует сохранять после успешной обработки пачки. Если процесс упал между чтением и ответом, возможен повтор. Для важных действий добавьте журнал идентификаторов событий и идемпотентность. Не прячьте поток в одном обработчике: сохраните вход, проверьте его, вызовите операцию и только затем обновите интерфейс.

Проверяем проект и добавляем свою функцию

Добавьте команды /help и /about, вынесите выбор ответа в чистую функцию и протестируйте её без сети. До правки запишите ожидаемое поведение одним предложением. После граничного теста повторите обычный сценарий.

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

Четыре проверки перед следующим шагом. Каждый следующий этап начинается после наблюдаемого результата.

Что запомнить и куда двигаться дальше

После учебного запуска замените бесконечный цикл на webhook, добавьте журнал ошибок и ограничьте команды понятным набором. Для закрепления откройте в статье про Discord webhook, в первом API на FastAPI и в Telegram-боте на Python.

Как изучить тему в Кодике

Сначала разберите формат данных и одну функцию, затем подключайте сеть, интерфейс или внешний сервис. Сначала восстановите главную функцию и проверьте её на трёх значениях.

Закрепите проект, переписав ключевую функцию по памяти и добавив собственный граничный случай. Базовый синтаксис закрепите через курс Python.

Что получится в итоге

Финальный экран показывает результат, состояние запроса и понятное сообщение об ошибке без раскрытия секретов.