{"id":31761532,"url":"https://github.com/green-api/max-demo-chatbot-golang","last_synced_at":"2025-10-09T21:53:28.355Z","repository":{"id":314224727,"uuid":"1053249994","full_name":"green-api/max-demo-chatbot-golang","owner":"green-api","description":"Go демо чатбот это пример чатбота написанного с помощью библиотеки Go chatbot MAX, которая разработана специально для написания чатботов с использованием сервиса GREEN-API.","archived":false,"fork":false,"pushed_at":"2025-10-08T08:20:54.000Z","size":2436,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-08T10:21:30.170Z","etag":null,"topics":["green-api","max-api","max-bot","max-chatbot","max-chatbot-golang"],"latest_commit_sha":null,"homepage":"https://green-api.com/max","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/green-api.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-09T07:33:31.000Z","updated_at":"2025-10-08T08:20:57.000Z","dependencies_parsed_at":"2025-09-12T16:02:08.101Z","dependency_job_id":null,"html_url":"https://github.com/green-api/max-demo-chatbot-golang","commit_stats":null,"previous_names":["green-api/max-demo-chatbot-golang"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/green-api/max-demo-chatbot-golang","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/green-api%2Fmax-demo-chatbot-golang","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/green-api%2Fmax-demo-chatbot-golang/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/green-api%2Fmax-demo-chatbot-golang/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/green-api%2Fmax-demo-chatbot-golang/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/green-api","download_url":"https://codeload.github.com/green-api/max-demo-chatbot-golang/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/green-api%2Fmax-demo-chatbot-golang/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002044,"owners_count":26083286,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["green-api","max-api","max-bot","max-chatbot","max-chatbot-golang"],"created_at":"2025-10-09T21:53:13.217Z","updated_at":"2025-10-09T21:53:28.340Z","avatar_url":"https://github.com/green-api.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# max-demo-chatbot-golang\n\n- [Documentation in English](README_EN.md).\n\nПример чатбота написанного на Golang с использованием API сервиса для Max [green-api.com](https://green-api.com/).\nЧатбот наглядно демонстрирует использование API для отправки текстовых сообщений, файлов, картинок, локаций, контактов, а также интегрирует OpenAI GPT для бесед с ИИ.\n\n\n## Содержание\n\n* [Установка среды для запуска чатбота](#установка-среды-для-запуска-чатбота)\n* [Запуск чатбота](#запуск-чатбота)\n* [Настройка чатбота](#настройка-чатбота)\n* [Использование](#использование)\n* [Структура кода](#структура-кода)\n* [Управление сообщениями](#управление-сообщениями)\n* [Функциональность GPT](#функциональность-gpt)\n\n\n## Установка среды для запуска чатбота\n\nДля запуска чатбота необходимо произвести установку среды Golang. Загрузите последний релиз, подходящий для вашей операционной системы, с [официального вебсайта](https://go.dev/dl/). Следуйте настройкам по умолчанию и завершите установку среды.\n\nПосле завершения необходимо проверить была ли среда развернута корректно. Для этого откройте командную строку (например, cmd или bash) и введите запрос:\n```\n    go version\n```\nДля корректной работы, ответом на введеный запрос должна быть версия Go не ниже:\n```\n    go version go 1.24\n```\n\nСкачайте и разархивируйте [zip-архив](https://github.com/green-api/max-demo-chatbot-golang) проекта или клонируйте его командой системы контроля версий:\n\n\u003cdetails\u003e\n\u003csummary\u003eКак установить систему контроля версий Git?\u003c/summary\u003e\n\nСкачайте и установите систему контроля версий Git, подходящую для используемой операционной системы, с [официального вебсайта](https://git-scm.com/downloads).\n\n\u003c/details\u003e\n\n```\ngit clone https://github.com/green-api/max-demo-chatbot-golang\n```\n\nОткройте проект в любой IDE.\n\nСреда для запуска чатбота готова, теперь необходимо произвести настройку и запустить чатбот на вашем аккаунте Max.\n\n## Запуск чатбота\n\nДля того, чтобы настроить чатбот на своем аккаунте Max, Вам необходимо перейти в [личный кабинет](https://console.green-api.com/) и зарегистрироваться. Для новых пользователей предоставлена [инструкция](https://green-api.com/docs/before-start/) для настройки аккаунта и получения необходимых для работы чатбота параметров, а именно:\n```\n    idInstance\n    apiTokenInstance\n```\n\nВам также понадобится API-ключ OpenAI для использования функциональности GPT. Вы можете получить его на [платформе OpenAI](https://platform.openai.com/).\n\nСоздайте файл `.env` в корне проекта со следующими переменными:\n```\nID_INSTANCE=ваш_id_инстанса\nAUTH_TOKEN=ваш_api_токен\nOPENAI_API_KEY=ваш_openai_api_ключ\n```\n\nНе забудьте включить все уведомления в настройках инстанса, чтобы чатбот мог сразу начать принимать сообщения.\n\nДалее можно запускать программу, для этого нажмите пуск в интерфейсе IDE или введите следующий запрос в командной строке:\n```\ngo run main.go\n```\nДанный запрос запустит работу чатбота. Процесс начинается с инициализации чатбота, которая включает в себя изменение настроек связанного инстанса.\n\nВ библиотеке [max-chatbot-golang](https://github.com/green-api/max-chatbot-golang) прописан механизм изменения настроек инстанса методом [SetSettings](https://green-api.com/docs/api/account/SetSettings/), который запускается при включении чатбота.\n\nВсе настройки по получению уведомлений выключены по умолчанию, чатбот включит следующие настройки:\n```\n    \"incomingWebhook\": \"yes\",\n    \"markIncomingMessagesReaded\": \"yes\"\n```\nкоторые отвечают за получение уведомлений о входящих сообщениях и опросах.\n\nПроцесс изменения настроек занимает несколько минут, в течении этого времени инстанс будет недоступен. Сообщения отправленные чатботу в это время не будут обработаны.\n\nПосле того, как будут применены настройки, произойдет удаление уведомлений о полученных ранее входящих сообщениях. Этот процесс так же прописан в библиотеке [max-chatbot-golang](https://github.com/green-api/max-chatbot-golang) и автоматически запускается после изменения настроек.\n\nЭто необходимо для того, чтобы чатбот не начал обрабатывать сообщения со старых чатов.\n\nПосле того, как изменения настроек и удаление входящих уведомлений будут исполнены, чатбот начнет стандартно отвечать на сообщения. Суммарно этот процесс занимает не больше 5 минут.\n\nЧтобы остановить работу чатбота, используйте сочетание клавиш `Ctrl + C` в командной строке.\n\n## Настройка чатбота\n\nПо умолчанию чатбот использует ссылки для выгрузки файлов из сети, однако пользователи могут добавить свои ссылки на файлы, одну для файла любого расширения pdf / docx /... и одну для картинки.\n\nСсылки должны вести на файлы из облачного хранилища или открытого доступа. В файле [`endpoints.go`](scenes/endpoints.go) есть следующий код для отправки файла:\n```go\ncase \"2\":\n    message.SendUrlFile(\n    \"https://storage.yandexcloud.net/sw-prod-03-test/ChatBot/corgi.pdf\",\n    \"corgi.pdf\",\n    util.GetString([]string{\"send_file_message\", lang})+util.GetString([]string{\"links\", lang, \"send_file_documentation\"}))\n```\nДобавьте ссылку на файл любого расширения в качестве первого параметра метода `answerWithUrlFile` и задайте имя файлу во втором параметре. Имя файла должно содержать расширение, например \"somefile.pdf\".\nДанная строка после изменения будет в следующем формате:\n```go\ncase \"2\":\n    message.SendUrlFile(\n    \"https://...somefile.pdf\",\n    \"corgi.pdf\",\n    util.GetString([]string{\"send_file_message\", lang})+util.GetString([]string{\"links\", lang, \"send_file_documentation\"}))\n```\n\nВсе изменения должны быть сохранены, после чего можно запускать чатбот. Для запуска чатбота вернитесь к [пункту 2](#запуск-чатбота).\n\n## Использование\n\nЕсли предыдущие шаги были выполнены, то на вашем аккаунте Max должен работать чатбот. Важно помнить, что пользователь должен быть авторизован в [личном кабинете](https://console.green-api.com/).\n\nТеперь вы можете отправлять сообщения чатботу!\n\nЧатбот откликнется на любое сообщение отправленное на аккаунт.\nТак как чатбот поддерживает 2 языка - русский и английский - то прежде чем поприветствовать собеседника, чатбот попросит выбрать язык общения:\n```\n1 - English\n2 - Русский\n```\nОтветьте 1 или 2, чтобы выбрать язык для дальнейшего общения. После того как вы отправите 2, чатбот пришлет приветственное сообщение на русском языке:\n```\nДобро пожаловать в GREEN-API чатбот, пользователь! GREEN-API предоставляет отправку данных следующих видов. Выберите цифру из списка, чтобы проверить как работает метод отправки\n\n1. Текстовое сообщение 📩\n2. Файл 📋\n3. Картинка 🖼\n4. Аудио 🎵\n5. 5. Видео 📽\n6. ...\n9. 🔥 Разговор с ChatGPT 🤖\n\nЧтобы вернуться в начало напишите стоп\n```\nВыбрав число из списка и отправив его, чатбот ответит каким API был отправлен данный тип сообщения и поделится ссылкой на информацию об API.\n\nНапример, отправив 1, пользователь получит в ответ:\n```\nЭто сообщение отправлено через sendMessage метод\n\nЧтобы узнать как работает метод, пройдите по ссылке\nhttps://green-api.com/docs/api/sending/SendMessage/\n```\n\n### Режим чата с GPT\n\nВыбрав пункт 9, вы можете взаимодействовать с моделью GPT от OpenAI:\n\n```\n🤖 Вы начали разговор с ChatGPT. \nЗадавайте любые вопросы, и ChatGPT постарается на них ответить.\nЧтобы вернуться в главное меню, напишите *меню*, *выход*, *стоп* или *назад*.\n```\n\nВ этом режиме ваши сообщения будут обрабатываться GPT, и вы будете получать интеллектуальные ответы. История беседы сохраняется на протяжении всей сессии, что позволяет вести контекстные диалоги.\n\nЧтобы выйти из режима GPT и вернуться в главное меню, напишите любую из команд выхода, например \"меню\", \"выход\", \"назад\" и т.д.\n\nЕсли отправить что-то помимо чисел 1-9, то чатбот лаконично ответит:\n```\nИзвините, я не совсем вас понял, напишите меню, чтобы посмотреть возможные опции\n```\nТак же пользователь может вызвать меню, отправив сообщение содержащее \"меню\". И отправив \"стоп\", пользователь завершит беседу с чатботом и получит сообщение:\n```\nСпасибо за использование чатбота GREEN-API, пользователь!\n```\n\n## Структура кода\n\nОсновной файл чатбота это [`main.go`](main.go), в нем находится функция `main` и с него начинается выполнение программы. В этом классе происходит инициализация объекта бота при помощи класса `BotFactory`, настройка и регистрация бота GPT, установка первой сцены и запуск бота.\n\n```go\nfunc main() {\n    // Загрузка переменных окружения\n    err := godotenv.Load(\".env\")\n    \n    // Инициализация базового бота\n    baseBot := chatbot.NewBot(idInstance, authToken)\n\n    // Инициализация и регистрация GPT бота\n    gptConfig := gptbot.GPTBotConfig{\n       IDInstance:       idInstance,\n       APITokenInstance: authToken,\n       OpenAIApiKey:     openaiToken,\n       Model:            gptbot.ModelGPT4o,\n       MaxHistoryLength: 10,\n       SystemMessage:    \"You are a helpful Max assistant.\",\n    }\n    gptHelper := gptbot.NewMaxGptBot(gptConfig)\n    registry.RegisterGptHelper(gptHelper)\n\n    // Установка начальной сцены и запуск бота\n    baseBot.SetStartScene(scenes.StartScene{})\n    baseBot.StartReceivingNotifications()\n}\n```\n\nДанный бот использует паттерн сцен для организации кода. Это значит, что логика чатбота разделена на фрагменты (сцены), сцена соответствует определенному состоянию диалога и отвечает за обработку ответа.\n\nДля каждого диалога одновременно активна может быть только одна сцена.\n\nНапример, первая сцена [`start.go`](scenes/start.go) отвечает за приветственное сообщение. Вне зависимости от текста сообщения, бот спрашивает какой язык удобен пользователю и включает следующую сцену, которая отвечает за обработку ответа.\n\nВсего в боте 5 сцен:\n\n- Сцена [`start.go`](scenes/start.go) - отвечает на любое входящее сообщение, отправляет список доступных языков. Запускает сцену `MainMenu`.\n- Сцена [`mainMenu.go`](scenes/mainMenu.go) - обрабатывает выбор пользователя и отправляет текст главного меню на выбранном языке. Запускает сцену `Endpoints`.\n- Сцена [`endpoints.go`](scenes/endpoints.go) - выполняет выбранный пользователем метод и отправляет описание метода на выбранном языке. Может переходить в GPT-сцену при выборе пункта 9.\n- Сцена [`createGroup.go`](scenes/createGroup.go) - сцена создает группу, если пользователь сказал, что добавил бота в свои контакты. Если нет, возвращается к сцене «endpoints».\n- Сцена [`gptScene.go`](scenes/gptScene.go) - обрабатывает режим беседы с GPT, обрабатывая сообщения пользователя через API OpenAI и поддерживая контекст беседы.\n\nФайл [`util.go`](util/util.go) содержит метод `IsSessionExpired()` который используется, чтобы снова устанавливать стартовую сцену, если боту не пишут более 2 минут.\n\nФайл [`ymlReader.go`](util/ymlReader.go) содержит метод `getString()` который возвращает строки из файла `strings.xml` по ключам. Этот файл используется для хранения текстов ответов бота.\n\nНовый компонент - модуль [`registry`](registry), который обеспечивает глобальную точку доступа к экземпляру GPT-бота.\n\n## Управление сообщениями\n\nКак и указывает чатбот в ответах, все сообщения отправлены через API. Документацию по методам отправки сообщений можно найти на сайте [green-api.com/docs/api/sending](https://green-api.com/docs/api/sending/).\n\nЧто касается получения сообщений, то сообщения вычитываются через HTTP API. Документацию по методам получения сообщений можно найти на сайте [green-api.com/docs/api/receiving/technology-http-api](https://green-api.com/docs/api/receiving/technology-http-api/).\n\nЧатбот использует библиотеку [max-chatbot-golang](https://github.com/green-api/max-chatbot-golang), где уже интегрированы методы отправки и получения сообщений, поэтому сообщения вычитываются автоматически, а отправка обычных текстовых сообщений упрощена.\n\nНапример, чатбот автоматически отправляет сообщение контакту, от которого получил сообщение:\n```go\n    message.AnswerWithText(util.GetString([]string{\"select_language\"}))\n```\nОднако другие методы отправки можно вызвать напрямую из библиотеки [Max-api-client-golang](https://github.com/green-api/Max-api-client-golang). Как, например, при получении аватара:\n```go\n    message.GreenAPI.Methods().Service().GetAvatar(chatId)\n```\n\n## Функциональность GPT\n\nЧатбот интегрируется с моделями GPT от OpenAI с помощью библиотеки [Max-chatgpt-go](https://github.com/green-api/max-chatgpt-go). Это позволяет боту вести интеллектуальные беседы с пользователями.\n\n### Как это работает\n\n1. **Инициализация**: GPT-бот инициализируется в `main.go` с конфигурацией, включающей API-ключ OpenAI и системный промпт.\n2. **Паттерн реестра**: Экземпляр бота хранится в реестре, чтобы быть доступным из любой сцены.\n3. **GPT-сцена**: Специальная сцена (`gptScene.go`) обрабатывает режим беседы с GPT.\n4. **Управление сессией**: GPT-сцена поддерживает историю беседы, используя данные сессии, что позволяет вести контекстные диалоги.\n5. **Команды выхода**: Пользователи могут выйти из режима GPT, используя различные команды на разных языках.\n\n## Лицензия\n\nЛицензировано на условиях [Creative Commons Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0)](https://creativecommons.org/licenses/by-nd/4.0/).\n\n[LICENSE](https://github.com/green-api/max-demo-chatbot-golang/blob/master/LICENCE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgreen-api%2Fmax-demo-chatbot-golang","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgreen-api%2Fmax-demo-chatbot-golang","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgreen-api%2Fmax-demo-chatbot-golang/lists"}