max-demo-chatbot-golang

• Documentation in English.

Пример чатбота написанного на Golang с использованием API сервиса для Max green-api.com. Чатбот наглядно демонстрирует использование API для отправки текстовых сообщений, файлов, картинок, локаций, контактов, а также интегрирует OpenAI GPT для бесед с ИИ.

Содержание

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

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

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

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

    go version

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

    go version go 1.24

Скачайте и разархивируйте zip-архив проекта или клонируйте его командой системы контроля версий:

Как установить систему контроля версий Git?

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

git clone https://github.com/green-api/max-demo-chatbot-golang

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

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

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

Для того, чтобы настроить чатбот на своем аккаунте Max, Вам необходимо перейти в личный кабинет и зарегистрироваться. Для новых пользователей предоставлена инструкция для настройки аккаунта и получения необходимых для работы чатбота параметров, а именно:

    idInstance
    apiTokenInstance

Вам также понадобится API-ключ OpenAI для использования функциональности GPT. Вы можете получить его на платформе OpenAI.

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

ID_INSTANCE=ваш_id_инстанса
AUTH_TOKEN=ваш_api_токен
OPENAI_API_KEY=ваш_openai_api_ключ

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

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

go run main.go

Данный запрос запустит работу чатбота. Процесс начинается с инициализации чатбота, которая включает в себя изменение настроек связанного инстанса.

В библиотеке max-chatbot-golang прописан механизм изменения настроек инстанса методом SetSettings, который запускается при включении чатбота.

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

    "incomingWebhook": "yes",
    "markIncomingMessagesReaded": "yes"

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

Процесс изменения настроек занимает несколько минут, в течении этого времени инстанс будет недоступен. Сообщения отправленные чатботу в это время не будут обработаны.

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

Это необходимо для того, чтобы чатбот не начал обрабатывать сообщения со старых чатов.

После того, как изменения настроек и удаление входящих уведомлений будут исполнены, чатбот начнет стандартно отвечать на сообщения. Суммарно этот процесс занимает не больше 5 минут.

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

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

По умолчанию чатбот использует ссылки для выгрузки файлов из сети, однако пользователи могут добавить свои ссылки на файлы, одну для файла любого расширения pdf / docx /... и одну для картинки.

Ссылки должны вести на файлы из облачного хранилища или открытого доступа. В файле endpoints.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". Данная строка после изменения будет в следующем формате:

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 должен работать чатбот. Важно помнить, что пользователь должен быть авторизован в личном кабинете.

Теперь вы можете отправлять сообщения чатботу!

Чатбот откликнется на любое сообщение отправленное на аккаунт. Так как чатбот поддерживает 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 и с него начинается выполнение программы. В этом классе происходит инициализация объекта бота при помощи класса BotFactory, настройка и регистрация бота GPT, установка первой сцены и запуск бота.

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 отвечает за приветственное сообщение. Вне зависимости от текста сообщения, бот спрашивает какой язык удобен пользователю и включает следующую сцену, которая отвечает за обработку ответа.

Всего в боте 5 сцен:

• Сцена start.go - отвечает на любое входящее сообщение, отправляет список доступных языков. Запускает сцену MainMenu.
• Сцена mainMenu.go - обрабатывает выбор пользователя и отправляет текст главного меню на выбранном языке. Запускает сцену Endpoints.
• Сцена endpoints.go - выполняет выбранный пользователем метод и отправляет описание метода на выбранном языке. Может переходить в GPT-сцену при выборе пункта 9.
• Сцена createGroup.go - сцена создает группу, если пользователь сказал, что добавил бота в свои контакты. Если нет, возвращается к сцене «endpoints».
• Сцена gptScene.go - обрабатывает режим беседы с GPT, обрабатывая сообщения пользователя через API OpenAI и поддерживая контекст беседы.

Файл util.go содержит метод IsSessionExpired() который используется, чтобы снова устанавливать стартовую сцену, если боту не пишут более 2 минут.

Файл ymlReader.go содержит метод getString() который возвращает строки из файла strings.xml по ключам. Этот файл используется для хранения текстов ответов бота.

Новый компонент - модуль registry, который обеспечивает глобальную точку доступа к экземпляру GPT-бота.

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

Как и указывает чатбот в ответах, все сообщения отправлены через API. Документацию по методам отправки сообщений можно найти на сайте green-api.com/docs/api/sending.

Что касается получения сообщений, то сообщения вычитываются через HTTP API. Документацию по методам получения сообщений можно найти на сайте green-api.com/docs/api/receiving/technology-http-api.

Чатбот использует библиотеку max-chatbot-golang, где уже интегрированы методы отправки и получения сообщений, поэтому сообщения вычитываются автоматически, а отправка обычных текстовых сообщений упрощена.

Например, чатбот автоматически отправляет сообщение контакту, от которого получил сообщение:

    message.AnswerWithText(util.GetString([]string{"select_language"}))

Однако другие методы отправки можно вызвать напрямую из библиотеки Max-api-client-golang. Как, например, при получении аватара:

    message.GreenAPI.Methods().Service().GetAvatar(chatId)

Функциональность GPT

Чатбот интегрируется с моделями GPT от OpenAI с помощью библиотеки 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).

LICENSE.