feat: initial commit

Author: AshLeigh-Fraxinus

.env

@@ -0,0 +1,2 @@
+BASE_URL=https://platform-api.max.ru
+TOKEN=YOUR_BOT_TOKEN

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GREEN-API
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,151 @@
+# MAX BOT API 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).        

assets/strings.yaml

@@ -0,0 +1,59 @@
+select_language: "1 - English \n2 - Русский"
+specify_language: "Please choose a language for further conversation\n1 - English \n2 - Русский"
+please_use_text: "Please enter a text message for further conversation with bot\n"
+welcome_message:
+  ru: "Добро пожаловать в MAX BOT API чат-бот, "
+  en: "Welcome to the MAX BOT API chatbot, "
+stop_message:
+  ru: "Спасибо за использование чат-бота MAX BOT API, "
+  en: "Thank you for using the MAX BOT API chatbot, "
+menu:
+  ru: "\n\nMAX BOT API предоставляет отправку данных следующих видов. \nВыберите цифру или нажмите кнопку!\n\n1. Текст 📩\n2. Файл 📋\n3. Картинка 🖼\n4. Аудио 🎵\n5. Видео 📽\n6. Контакт 📱\n7. Геолокация 🌎\n8. О боте 🦎\n\nЧтобы вернуться в начало, напишите *стоп* или *0*"
+  en: "\n\nMAX BOT API provides sending the following types of data. \nSelect a number or press a button!\n\n1. Text 📩\n2. File 📋\n3. Image 🖼\n4. Audio 🎵\n5. Video 📽\n6. Contact 📱\n7. Geolocation 🌎\n8. About 🦎\n\nTo restart, type *stop* or *0*"
+about_chatbot:
+  ru: "**Python MAX BOT API чат-бот** предназначен для демонстрации возможностей MAX BOT API.\n\nКод открыт, на его основе Вы легко сможете написать своего бота."
+  en: "**Python MAX BOT API chatbot** is designed to demonstrate the capabilities of the MAX BOT API.\n\nThe code is open source, and you can easily write your own bot on its basis."
+send_text_message:
+  ru: "Это сообщение отправлено через метод **SendMessage**.\n\n**Документация**: \n\n"
+  en: "This message is sent via **SendMessage** method.\n\n**Documentation**: \n\n"
+send_file_message:
+  ru: "Этот файл отправлен методом **UploadFile**.\nФайл содержит фотографию корги в расширении pdf!\n\n**Документация**: \n\n"
+  en: "This file is sent via **UploadFile** method.\nThe file is image of corgi in the pdf extension!\n\n**Documentation**: \n\n"
+send_image_message:
+  ru: "Это фото отправлено методом **UploadFile**. Корги поднимет вам настроение! 🥳\n\n**Документация**: \n\n"
+  en: "This image is sent via **UploadFile** method. Hope a little corgi will lighten your mood! 🥳\n\n**Documentation**: \n\n"
+send_audio_message:
+  ru: "Это аудио отправлено методом **UploadFile**.\n\n**Документация**: \n\n"
+  en: "This audio is sent using the **UploadFile** method.\n\n**Documentation**: \n\n"
+send_video_message:
+  ru: "Это видео отправлено методом **UploadFile**.\n\n**Документация**: \n\n"
+  en: "This video is sent via **UploadFile** method.\n\n**Documentation**: \n\n"
+send_contact_message:
+  ru: "Следующий контакт будет отправлен методом **SendMessage**.\n\n**Документация**: \n\n"
+  en: "The following contact to be sent via **SendMessage** method.\n\n**Documentation**: \n\n"
+send_location_message:
+  ru: "Следующая геолокация будет отправлена методом **SendMessage**.\nЭто координаты острова Мальта!\n\n**Документация**: \n\n"
+  en: "The following location to be sent via **SendMessage** method.\nThese are the coordinates of Malta island!\n\n**Documentation**: \n\n"
+not_recognized_message:
+  ru: "Извините, я не совсем вас понял 😔, напишите меню, чтобы посмотреть возможные опции"
+  en: "Sorry, I cannot understand what you are talking about 😔, type in menu to see the available options"
+links:
+  send_text_documentation: "https://green-api.com/max-bot-api/docs/api/messages/SendMessage/"
+  send_file_documentation: "https://green-api.com/max-bot-api/docs/api/upload/UploadFile/"
+  send_contact_documentation: "https://green-api.com/max-bot-api/docs/api/messages/SendMessage/"
+  send_location_documentation: "https://green-api.com/max-bot-api/docs/api/messages/SendMessage/"
+  maxbot_api_client_python_documentation: "https://github.com/green-api/maxbot-api-client-python/blob/master/README.md"
+  greenapi_website: "https://green-api.com/max"
+  max_documentation: "https://dev.max.ru/docs-api"
+link_to_source_code:
+  ru: "\n\n🗒️ Исходный код чатбота на GitHub:\nhttps://github.com/green-api/maxbot-demo-chatbot-python"
+  en: "\n\n🗒️ Source code of the chatbot on GitHub:\nhttps://github.com/green-api/maxbot-demo-chatbot-python"
+link_to_max:
+  ru: "\n\n📚 Документация MAX API:\nhttps://dev.max.ru/docs-api"
+  en: "\n\n📚 MAX API Documentation:\nhttps://dev.max.ru/docs-api"
+link_to_docs:
+  ru: "\n\n📚 Документация MAX BOT API:\nhttps://green-api.com/max-bot-api/docs/"
+  en: "\n\n📚 MAX BOT API Documentation:\nhttps://green-api.com/max-bot-api/docs/"
+bot_name:
+  ru: "MAX BOT API чат-бот"
+  en: "MAX BOT API chatbot"

main.py

@@ -0,0 +1,61 @@
+import asyncio, logging, os, time
+from dotenv import load_dotenv
+
+from maxbot_chatbot_python import Bot, MapStateManager
+from maxbot_api_client_python import API, Config
+from scenes.start import StartScene
+
+logger = logging.getLogger(__name__)
+
+async def main():
+    if not load_dotenv():
+        logger.warning("Error loading .env file or it does not exist")
+
+    cfg = Config(
+        base_url=os.getenv("BASE_URL"),
+        token=os.getenv("TOKEN"),
+        ratelimiter=25,
+        timeout=30
+    )
+
+    async with API(cfg) as api_client:
+        bot = Bot(api_client)
+        
+        start_scene = StartScene()
+        bot.state_manager = MapStateManager(init_data={})
+        bot.state_manager.set_start_scene(start_scene)
+
+        start_time = time.time()
+
+        @bot.router.register("message_created")
+        @bot.router.register("message_callback")
+        async def scene_handler(notification):
+            if notification.update and getattr(notification.update, 'timestamp', 0) < (start_time * 1000):
+                return
+            
+            notification.create_state_id()
+
+            if not bot.state_manager.get(notification.state_id):
+                bot.state_manager.create(notification.state_id)
+
+            current_scene = notification.get_current_scene()
+            if not current_scene:
+                current_scene = start_scene
+                notification.activate_next_scene(current_scene)
+
+            if hasattr(current_scene, 'execute'):
+                await current_scene.execute(notification)
+            else:
+                logger.error(f"Current scene {type(current_scene).__name__} does not implement 'execute'")
+
+        try:
+            logger.info("Bot is polling...")
+            await bot.start_polling()
+        except asyncio.CancelledError:
+            logger.info("The bot has been stopped")
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        logger.info("The bot has been stopped by user")

pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "maxbot-demo-chatbot-python"
+version = "1.1.1"
+description = "Python demo chatbot for MAX BOT API"
+readme = "README.md"
+authors = [{ name = "Green-API" }]
+requires-python = ">=3.12"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "maxbot-api-client-python>=1.2.2",
+    "maxbot-chatbot-python>=1.1.1",
+    "httpx>=0.28.1",
+    "python-dotenv>=1.0.1",
+    "PyYAML>=6.0.2",
+    "pydantic>=2.10.6"
+]
+
+[project.urls]
+Homepage = "https://github.com/green-api/maxbot-demo-chatbot-python"

requirements.txt

@@ -0,0 +1,6 @@
+maxbot-api-client-python>=1.2.0
+maxbot-chatbot-python>=1.1.1
+python-dotenv>=1.0.1
+PyYAML>=6.0.2
+httpx>=0.28.1
+pydantic>=2.10.6