https://github.com/green-api/max-demo-chatbot-golang
Go демо чатбот это пример чатбота написанного с помощью библиотеки Go chatbot MAX, которая разработана специально для написания чатботов с использованием сервиса GREEN-API.
https://github.com/green-api/max-demo-chatbot-golang
green-api max-api max-bot max-chatbot max-chatbot-golang
Last synced: 8 months ago
JSON representation
Go демо чатбот это пример чатбота написанного с помощью библиотеки Go chatbot MAX, которая разработана специально для написания чатботов с использованием сервиса GREEN-API.
- Host: GitHub
- URL: https://github.com/green-api/max-demo-chatbot-golang
- Owner: green-api
- License: other
- Created: 2025-09-09T07:33:31.000Z (9 months ago)
- Default Branch: master
- Last Pushed: 2025-10-08T08:20:54.000Z (8 months ago)
- Last Synced: 2025-10-08T10:21:30.170Z (8 months ago)
- Topics: green-api, max-api, max-bot, max-chatbot, max-chatbot-golang
- Language: Go
- Homepage: https://green-api.com/max
- Size: 2.32 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# max-demo-chatbot-golang
- [Documentation in English](README_EN.md).
Пример чатбота написанного на Golang с использованием API сервиса для Max [green-api.com](https://green-api.com/).
Чатбот наглядно демонстрирует использование API для отправки текстовых сообщений, файлов, картинок, локаций, контактов, а также интегрирует OpenAI GPT для бесед с ИИ.
## Содержание
* [Установка среды для запуска чатбота](#установка-среды-для-запуска-чатбота)
* [Запуск чатбота](#запуск-чатбота)
* [Настройка чатбота](#настройка-чатбота)
* [Использование](#использование)
* [Структура кода](#структура-кода)
* [Управление сообщениями](#управление-сообщениями)
* [Функциональность GPT](#функциональность-gpt)
## Установка среды для запуска чатбота
Для запуска чатбота необходимо произвести установку среды Golang. Загрузите последний релиз, подходящий для вашей операционной системы, с [официального вебсайта](https://go.dev/dl/). Следуйте настройкам по умолчанию и завершите установку среды.
После завершения необходимо проверить была ли среда развернута корректно. Для этого откройте командную строку (например, cmd или bash) и введите запрос:
```
go version
```
Для корректной работы, ответом на введеный запрос должна быть версия Go не ниже:
```
go version go 1.24
```
Скачайте и разархивируйте [zip-архив](https://github.com/green-api/max-demo-chatbot-golang) проекта или клонируйте его командой системы контроля версий:
Как установить систему контроля версий Git?
Скачайте и установите систему контроля версий Git, подходящую для используемой операционной системы, с [официального вебсайта](https://git-scm.com/downloads).
```
git clone https://github.com/green-api/max-demo-chatbot-golang
```
Откройте проект в любой IDE.
Среда для запуска чатбота готова, теперь необходимо произвести настройку и запустить чатбот на вашем аккаунте Max.
## Запуск чатбота
Для того, чтобы настроить чатбот на своем аккаунте Max, Вам необходимо перейти в [личный кабинет](https://console.green-api.com/) и зарегистрироваться. Для новых пользователей предоставлена [инструкция](https://green-api.com/docs/before-start/) для настройки аккаунта и получения необходимых для работы чатбота параметров, а именно:
```
idInstance
apiTokenInstance
```
Вам также понадобится API-ключ OpenAI для использования функциональности GPT. Вы можете получить его на [платформе OpenAI](https://platform.openai.com/).
Создайте файл `.env` в корне проекта со следующими переменными:
```
ID_INSTANCE=ваш_id_инстанса
AUTH_TOKEN=ваш_api_токен
OPENAI_API_KEY=ваш_openai_api_ключ
```
Не забудьте включить все уведомления в настройках инстанса, чтобы чатбот мог сразу начать принимать сообщения.
Далее можно запускать программу, для этого нажмите пуск в интерфейсе IDE или введите следующий запрос в командной строке:
```
go run main.go
```
Данный запрос запустит работу чатбота. Процесс начинается с инициализации чатбота, которая включает в себя изменение настроек связанного инстанса.
В библиотеке [max-chatbot-golang](https://github.com/green-api/max-chatbot-golang) прописан механизм изменения настроек инстанса методом [SetSettings](https://green-api.com/docs/api/account/SetSettings/), который запускается при включении чатбота.
Все настройки по получению уведомлений выключены по умолчанию, чатбот включит следующие настройки:
```
"incomingWebhook": "yes",
"markIncomingMessagesReaded": "yes"
```
которые отвечают за получение уведомлений о входящих сообщениях и опросах.
Процесс изменения настроек занимает несколько минут, в течении этого времени инстанс будет недоступен. Сообщения отправленные чатботу в это время не будут обработаны.
После того, как будут применены настройки, произойдет удаление уведомлений о полученных ранее входящих сообщениях. Этот процесс так же прописан в библиотеке [max-chatbot-golang](https://github.com/green-api/max-chatbot-golang) и автоматически запускается после изменения настроек.
Это необходимо для того, чтобы чатбот не начал обрабатывать сообщения со старых чатов.
После того, как изменения настроек и удаление входящих уведомлений будут исполнены, чатбот начнет стандартно отвечать на сообщения. Суммарно этот процесс занимает не больше 5 минут.
Чтобы остановить работу чатбота, используйте сочетание клавиш `Ctrl + C` в командной строке.
## Настройка чатбота
По умолчанию чатбот использует ссылки для выгрузки файлов из сети, однако пользователи могут добавить свои ссылки на файлы, одну для файла любого расширения pdf / docx /... и одну для картинки.
Ссылки должны вести на файлы из облачного хранилища или открытого доступа. В файле [`endpoints.go`](scenes/endpoints.go) есть следующий код для отправки файла:
```go
case "2":
message.SendUrlFile(
"https://storage.yandexcloud.net/sw-prod-03-test/ChatBot/corgi.pdf",
"corgi.pdf",
util.GetString([]string{"send_file_message", lang})+util.GetString([]string{"links", lang, "send_file_documentation"}))
```
Добавьте ссылку на файл любого расширения в качестве первого параметра метода `answerWithUrlFile` и задайте имя файлу во втором параметре. Имя файла должно содержать расширение, например "somefile.pdf".
Данная строка после изменения будет в следующем формате:
```go
case "2":
message.SendUrlFile(
"https://...somefile.pdf",
"corgi.pdf",
util.GetString([]string{"send_file_message", lang})+util.GetString([]string{"links", lang, "send_file_documentation"}))
```
Все изменения должны быть сохранены, после чего можно запускать чатбот. Для запуска чатбота вернитесь к [пункту 2](#запуск-чатбота).
## Использование
Если предыдущие шаги были выполнены, то на вашем аккаунте Max должен работать чатбот. Важно помнить, что пользователь должен быть авторизован в [личном кабинете](https://console.green-api.com/).
Теперь вы можете отправлять сообщения чатботу!
Чатбот откликнется на любое сообщение отправленное на аккаунт.
Так как чатбот поддерживает 2 языка - русский и английский - то прежде чем поприветствовать собеседника, чатбот попросит выбрать язык общения:
```
1 - English
2 - Русский
```
Ответьте 1 или 2, чтобы выбрать язык для дальнейшего общения. После того как вы отправите 2, чатбот пришлет приветственное сообщение на русском языке:
```
Добро пожаловать в GREEN-API чатбот, пользователь! GREEN-API предоставляет отправку данных следующих видов. Выберите цифру из списка, чтобы проверить как работает метод отправки
1. Текстовое сообщение 📩
2. Файл 📋
3. Картинка 🖼
4. Аудио 🎵
5. 5. Видео 📽
6. ...
9. 🔥 Разговор с ChatGPT 🤖
Чтобы вернуться в начало напишите стоп
```
Выбрав число из списка и отправив его, чатбот ответит каким API был отправлен данный тип сообщения и поделится ссылкой на информацию об API.
Например, отправив 1, пользователь получит в ответ:
```
Это сообщение отправлено через sendMessage метод
Чтобы узнать как работает метод, пройдите по ссылке
https://green-api.com/docs/api/sending/SendMessage/
```
### Режим чата с GPT
Выбрав пункт 9, вы можете взаимодействовать с моделью GPT от OpenAI:
```
🤖 Вы начали разговор с ChatGPT.
Задавайте любые вопросы, и ChatGPT постарается на них ответить.
Чтобы вернуться в главное меню, напишите *меню*, *выход*, *стоп* или *назад*.
```
В этом режиме ваши сообщения будут обрабатываться GPT, и вы будете получать интеллектуальные ответы. История беседы сохраняется на протяжении всей сессии, что позволяет вести контекстные диалоги.
Чтобы выйти из режима GPT и вернуться в главное меню, напишите любую из команд выхода, например "меню", "выход", "назад" и т.д.
Если отправить что-то помимо чисел 1-9, то чатбот лаконично ответит:
```
Извините, я не совсем вас понял, напишите меню, чтобы посмотреть возможные опции
```
Так же пользователь может вызвать меню, отправив сообщение содержащее "меню". И отправив "стоп", пользователь завершит беседу с чатботом и получит сообщение:
```
Спасибо за использование чатбота GREEN-API, пользователь!
```
## Структура кода
Основной файл чатбота это [`main.go`](main.go), в нем находится функция `main` и с него начинается выполнение программы. В этом классе происходит инициализация объекта бота при помощи класса `BotFactory`, настройка и регистрация бота GPT, установка первой сцены и запуск бота.
```go
func main() {
// Загрузка переменных окружения
err := godotenv.Load(".env")
// Инициализация базового бота
baseBot := chatbot.NewBot(idInstance, authToken)
// Инициализация и регистрация GPT бота
gptConfig := gptbot.GPTBotConfig{
IDInstance: idInstance,
APITokenInstance: authToken,
OpenAIApiKey: openaiToken,
Model: gptbot.ModelGPT4o,
MaxHistoryLength: 10,
SystemMessage: "You are a helpful Max assistant.",
}
gptHelper := gptbot.NewMaxGptBot(gptConfig)
registry.RegisterGptHelper(gptHelper)
// Установка начальной сцены и запуск бота
baseBot.SetStartScene(scenes.StartScene{})
baseBot.StartReceivingNotifications()
}
```
Данный бот использует паттерн сцен для организации кода. Это значит, что логика чатбота разделена на фрагменты (сцены), сцена соответствует определенному состоянию диалога и отвечает за обработку ответа.
Для каждого диалога одновременно активна может быть только одна сцена.
Например, первая сцена [`start.go`](scenes/start.go) отвечает за приветственное сообщение. Вне зависимости от текста сообщения, бот спрашивает какой язык удобен пользователю и включает следующую сцену, которая отвечает за обработку ответа.
Всего в боте 5 сцен:
- Сцена [`start.go`](scenes/start.go) - отвечает на любое входящее сообщение, отправляет список доступных языков. Запускает сцену `MainMenu`.
- Сцена [`mainMenu.go`](scenes/mainMenu.go) - обрабатывает выбор пользователя и отправляет текст главного меню на выбранном языке. Запускает сцену `Endpoints`.
- Сцена [`endpoints.go`](scenes/endpoints.go) - выполняет выбранный пользователем метод и отправляет описание метода на выбранном языке. Может переходить в GPT-сцену при выборе пункта 9.
- Сцена [`createGroup.go`](scenes/createGroup.go) - сцена создает группу, если пользователь сказал, что добавил бота в свои контакты. Если нет, возвращается к сцене «endpoints».
- Сцена [`gptScene.go`](scenes/gptScene.go) - обрабатывает режим беседы с GPT, обрабатывая сообщения пользователя через API OpenAI и поддерживая контекст беседы.
Файл [`util.go`](util/util.go) содержит метод `IsSessionExpired()` который используется, чтобы снова устанавливать стартовую сцену, если боту не пишут более 2 минут.
Файл [`ymlReader.go`](util/ymlReader.go) содержит метод `getString()` который возвращает строки из файла `strings.xml` по ключам. Этот файл используется для хранения текстов ответов бота.
Новый компонент - модуль [`registry`](registry), который обеспечивает глобальную точку доступа к экземпляру GPT-бота.
## Управление сообщениями
Как и указывает чатбот в ответах, все сообщения отправлены через API. Документацию по методам отправки сообщений можно найти на сайте [green-api.com/docs/api/sending](https://green-api.com/docs/api/sending/).
Что касается получения сообщений, то сообщения вычитываются через HTTP API. Документацию по методам получения сообщений можно найти на сайте [green-api.com/docs/api/receiving/technology-http-api](https://green-api.com/docs/api/receiving/technology-http-api/).
Чатбот использует библиотеку [max-chatbot-golang](https://github.com/green-api/max-chatbot-golang), где уже интегрированы методы отправки и получения сообщений, поэтому сообщения вычитываются автоматически, а отправка обычных текстовых сообщений упрощена.
Например, чатбот автоматически отправляет сообщение контакту, от которого получил сообщение:
```go
message.AnswerWithText(util.GetString([]string{"select_language"}))
```
Однако другие методы отправки можно вызвать напрямую из библиотеки [Max-api-client-golang](https://github.com/green-api/Max-api-client-golang). Как, например, при получении аватара:
```go
message.GreenAPI.Methods().Service().GetAvatar(chatId)
```
## Функциональность GPT
Чатбот интегрируется с моделями GPT от OpenAI с помощью библиотеки [Max-chatgpt-go](https://github.com/green-api/max-chatgpt-go). Это позволяет боту вести интеллектуальные беседы с пользователями.
### Как это работает
1. **Инициализация**: GPT-бот инициализируется в `main.go` с конфигурацией, включающей API-ключ OpenAI и системный промпт.
2. **Паттерн реестра**: Экземпляр бота хранится в реестре, чтобы быть доступным из любой сцены.
3. **GPT-сцена**: Специальная сцена (`gptScene.go`) обрабатывает режим беседы с GPT.
4. **Управление сессией**: GPT-сцена поддерживает историю беседы, используя данные сессии, что позволяет вести контекстные диалоги.
5. **Команды выхода**: Пользователи могут выйти из режима GPT, используя различные команды на разных языках.
## Лицензия
Лицензировано на условиях [Creative Commons Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0)](https://creativecommons.org/licenses/by-nd/4.0/).
[LICENSE](https://github.com/green-api/max-demo-chatbot-golang/blob/master/LICENCE).