maxbot-demo-chatbot-python

Пример чат-бота, написанного на Python с использованием SDK maxbot-chatbot-python и maxbot-api-client-python от GREEN-API.

Этот чат-бот демонстрирует возможности MAX BOT API по отправке текстовых сообщений, медиафайлов (картинки, аудио, видео, PDF), геолокаций и контактов с использованием системы сцен и интерактивных кнопок.

Содержание

• Установка среды для запуска
• Запуск чат-бота
• Настройка чат-бота
• Использование
• Структура кода
• Управление сообщениями
• Лицензия

Установка

Убедитесь, что у вас установлен Python версии 3.12 или выше:

python --version

Установите библиотеку:

git clone https://github.com/green-api/maxbot-demo-chatbot-python

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

Запуск чат-бота

Параметры конфигурации:

• BASE_URL - Базовый URL-адрес серверов платформы MaxBot. Все методы API будут отправляться по этому корневому адресу. Актуальный адрес указан в официальной документации.
• TOKEN - Уникальный секретный ключ авторизации (API-ключ) вашего бота. Получить его можно в личном кабинете после регистрации или создании бота на платформе business.max.ru.
• ratelimiter - Встроенный ограничитель частоты запросов. Он контролирует количество исходящих запросов в секунду (RPS), защищая бота от блокировки со стороны сервера за превышение лимитов. Рекомендуемое значение — не менее 25.
• timeout - Максимальное время ожидания ответа от сервера (в секундах). Если сервер не ответит в течение этого времени, запрос будет завершен с ошибкой. Оптимальное значение — 30 секунд.

1. Создайте файл .env в корневой директории проекта.
2. Добавьте в него ваши данные:

BASE_URL=https://platform-api.max.ru
TOKEN=1A2B3C4D5E6F7G8H9I0J9K8L7M6N5O4P3Q3R2S1T2U3V4W5X6Y7Z

Значение ratelimiter и timeout можно изменить в файле main.py перед его запуском.

3. Запустите бота командой:

python main.py

Программа инициализирует клиент, настроит менеджер состояний и запустит polling для получения уведомлений в реальном времени. Для остановки нажмите Ctrl + C.

Настройка чат-бота

Вы можете изменить медиафайлы, которые бот отправляет пользователям. Ссылки на файлы находятся в файле scenes/endpoints.py.

Например, для изменения PDF-файла найдите следующий блок:

elif text_lower in ["2", "/file"]:
    await n.reply_with_media(
        t(lang, "send_file_message") + t(lang, "links.send_file_documentation"),
        "markdown",
        "https://storage.yandexcloud.net/your-link/file.pdf", 
        self.get_control_buttons(lang)
    )

Замените URL "https://storage.yandexcloud.net/your-link/file.pdf" на прямую ссылку вашего файла.

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

Если предыдущие шаги были выполнены, ваш бот будет готов к приему сообщений.

Напишите боту любое текстовое сообщение (например, /start). Чат-бот поддерживает 2 языка, поэтому сначала он предложит выбрать язык с помощью клавиатуры:

Please select your language: 
Пожалуйста, выберите язык:
[English] [Русский]

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

Добро пожаловать в MAX BOT API чат-бот, {Имя_Пользователя}! 

GREEN-API предоставляет отправку данных следующих видов. 
Выберите цифру или нажмите кнопку!

1. Текст 📩
2. Файл 📋
3. Картинка 🖼
4. Аудио 🎵
5. Видео 📽
6. Контакт 📱
7. Геолокация 🌎
8. О боте 🦎

Чтобы вернуться в начало, напишите *стоп* или *0*

Нажимая на кнопки (или отправляя соответствующие цифры), бот будет присылать вам демонстрационные сообщения с использованием различных методов MAX API (фотографии, голосовые сообщения, файлы) и прикреплять ссылки на официальную документацию.

Структура кода

Основной файл чат-бота — это main.py. В нем находится функция main, с которой начинается выполнение программы.

Данный бот использует паттерн сцен для организации кода. Логика разделена на фрагменты (сцены), каждая из которых соответствует определенному состоянию диалога:

• scenes/start.py — приветственная сцена. Отвечает за выбор языка и инициализацию данных пользователя.
• scenes/main_menu.py — формирует главное меню, отправляет приветственное изображение и переключает контекст на рабочие эндпоинты.
• scenes/endpoints.py — содержит логику обработки всех функциональных кнопок (отправка текста, медиа, контактов).

Тексты сообщений вынесены отдельно и хранятся в файле assets/strings.yaml. Для получения нужной строки в зависимости от языка используется утилита перевода utils/yml_reader.py.

Управление сообщениями

Все взаимодействия реализованы через MAX API с использованием Python-библиотек:

• maxbot-api-client-python — базовый клиент для работы с API.
• maxbot-chatbot-python — фреймворк для создания ботов со сценами, состояниями и удобными обертками.

Отправка сообщений максимально упрощена благодаря методам объекта Notification. Например, отправка локации:

notification.reply_with_location(
    lat=51.5074, 
    lon=-0.1278
)

Или отправка медиафайла:

notification.reply_with_media(
    text="Look at this!",
    format_type="markdown",
    file_source="https://example.com/image.jpg"
)

Все доступные методы API описаны в официальной документации.
Полную документацию по MAX API можно найти на официальном портале разработчиков: dev.max.ru/docs-api.