maxbot-demo-chatbot-go

Пример чат-бота, написанного на Golang с использованием maxbot-demo-chatbot-go SDK от GREEN-API. Чат-бот наглядно демонстрирует использование API для отправки текстовых сообщений, файлов, картинок, аудио, видео, локаций и контактов с помощью интерактивных кнопок (меню).

Содержание

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

Установка среды для запуска чат-бота

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

После завершения необходимо проверить, была ли среда развернута корректно. Для этого откройте командную строку (например, cmd или bash) и введите запрос:

go version

Для корректной работы ответом на введенный запрос должна быть версия Go не ниже:

go version go 1.25

Скачайте и разархивируйте zip-архив проекта:

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

Откройте проект в любой IDE.

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

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

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

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

Создайте файл .env в корне проекта и внесите в него параметры бота:

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

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

Далее можно запускать программу. Для этого нажмите "Пуск" в интерфейсе IDE или введите следующий запрос в командной строке:

go run main.go

Данный запрос запустит работу чат-бота. Процесс начнется с инициализации клиента, установки менеджера состояний и запуска поллинга (получения входящих уведомлений).

Чтобы остановить работу чат-бота, используйте сочетание клавиш Ctrl + C в командной строке.

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

По умолчанию чат-бот использует прямые ссылки для выгрузки медиафайлов из облачного хранилища Яндекс. Пользователи могут изменить ссылки на свои файлы.

Ссылки должны вести на файлы из облачного хранилища или открытого доступа. В файле scenes/endpoints.go есть следующий код для отправки файла (на примере PDF):

	case "2", "/file":
		n.ReplyWithMedia(
			util.T(lang, "send_file_message")+util.T(lang, "links.send_file_documentation"),
			m.Markdown,
			"https://storage.yandexcloud.net/sw-prod-03-test/ChatBot/corgi.pdf",
		)

Замените URL "https://storage.yandexcloud.net/sw-prod-03-test/ChatBot/corgi.pdf" на прямую ссылку вашего файла. Аналогичным образом вы можете заменить ссылки на изображения (corgi.jpg), аудио (Audio_bot.mp3) и видео (Video_bot_ru.mp4) в соответствующих блоках case.

Все изменения должны быть сохранены, после чего нужно перезапустить чат-бот.

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

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

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

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

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

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

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

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

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

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

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

Основной файл чат-бота — это main.go. В нем находится функция main, с которой начинается выполнение программы. Здесь происходит инициализация бота, настройка маршрутизатора (Router), менеджера состояний (StateManager) и запуск процесса поллинга.

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

• scenes/start.go — стартовая сцена. Обрабатывает первые сообщения и команду /start. Запрашивает у пользователя предпочтительный язык и передает управление следующей сцене.
• scenes/main_menu.go — сцена главного меню. Сохраняет выбранный язык в состояние диалога, отправляет приветственную картинку и клавиатуру с разделами. Запускает сцену EndpointsScene.
• scenes/endpoints.go — основная рабочая сцена. Обрабатывает нажатия кнопок (callbacks) и текстовые команды (1-8, /image, /video и т.д.). Вызывает соответствующие методы отправки медиа/текста и прикрепляет кнопки Меню и Стоп.

Тексты сообщений вынесены отдельно и хранятся в файле strings.yaml. Для получения нужной строки в зависимости от языка используется утилита перевода (util.T(lang, "key")).

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

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

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

Бот подписывается на события TypeMessageCreated (входящие текстовые сообщения) и TypeMessageCallback (нажатия на кнопки inline-клавиатуры).

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

n.ReplyWithLocation(35.888171, 14.440230)

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

n.ReplyWithMedia(текст_сообщения, тип_форматирования_текста, ссылка_на_файл)

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

Лицензия

Лицензировано на условиях Creative Commons Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0).