Metadata-Version: 2.4
Name: maxbot-demo-chatbot-python
Version: 1.1.0
Summary: Python demo chatbot for MAX bot
Home-page: https://github.com/green-api/maxbot-demo-chatbot-python
Author: Green-API
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: maxbot-api-client-python>=1.1.2
Requires-Dist: maxbot-chatbot-python>=1.1.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: python-dotenv>=1.0.1
Requires-Dist: PyYAML>=6.0.2
Requires-Dist: pydantic>=2.10.6
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# maxbot-demo-chatbot-python

Пример чат-бота, написанного на **Python** с использованием **SDK** [maxbot-chatbot-python](https://github.com/green-api/maxbot-chatbot-python) и [maxbot-api-client-python](https://github.com/green-api/maxbot-api-client-python) от [GREEN-API](https://green-api.com/max-bot-api).

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

## Содержание

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

## Установка

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

```bash
python --version
```

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

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

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

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

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

- `BASE_URL` - Базовый URL-адрес серверов платформы MaxBot. Все методы API будут маршрутизироваться по этому корневому адресу. Актуальный адрес указан в [официальной документации](https://dev.max.ru/docs-api).
- `TOKEN` - Уникальный секретный ключ авторизации (API-ключ) вашего бота. Получить его можно в личном кабинете после [регистрации или создании бота](https://green-api.com/max-bot-api/docs/before-start/) на платформе [business.max.ru](https://business.max.ru/).
- `ratelimiter` - Встроенный ограничитель частоты запросов. Он контролирует количество исходящих запросов в секунду (RPS), защищая бота от блокировки со стороны сервера за превышение лимитов. Рекомендуемое значение — не менее 25.
- `timeout` - Максимальное время ожидания ответа от сервера (в секундах). Если сервер не ответит в течение этого времени, запрос будет завершен с ошибкой. Оптимальное значение — 30 секунд.

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

```bash
BASE_URL=https://platform-api.max.ru
TOKEN=1A2B3C4D5E6F7G8H9I0J9K8L7M6N5O4P3Q3R2S1T2U3V4W5X6Y7Z
```
> Значение `ratelimiter` и `timeout` можно изменить в файле [main.py](./main.py) перед его запуском.

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

```bash
python main.py
```

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

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

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

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

```python
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 языка, поэтому сначала он предложит выбрать язык с помощью клавиатуры:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

* [maxbot-api-client-python](https://github.com/green-api/maxbot-api-client-python) — базовый клиент для работы с API.
* [maxbot-chatbot-python](https://github.com/green-api/maxbot-chatbot-python) — фреймворк для создания ботов со сценами, состояниями и удобными обертками.

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

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

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

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

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