GREEN-API демо чатбот#

Go демо чатбот это пример чатбота написанного с помощью библиотеки Go chatbot Whatsapp, которая разработана специально для написания чатботов с использованием сервиса Green API.

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

Отсканируйте QR-код или перейдите по ссылке для начала общения с чатботом

Ссылка на бота

Для запуска чатбота на собственном Whatsapp аккаунте следуйте инструкциям:

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

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

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

    go version

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

    go version go 1.19

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

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

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

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

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

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

2. Запуск чатбота#

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

    idInstance
    apiTokenInstance

Не забудьте включить все уведомления в настройках инстанса, чтобы чатбот мог сразу начать принимать сообщения. После получения данных параметров, найдите класс main.go и введите idInstance и apiTokenInstance в значения констант. Инициализация данных необходима для связывания бота с Вашим Whatsapp аккаунтом:

    bot := chatbot.NewBot("{INSTANCE}", "{TOKEN}")

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

    go run main.go

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

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

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

    _, err := bot.GreenAPI.Methods().Account().SetSettings(map[string]interface{}{
        "incomingWebhook":            "yes",
        "outgoingMessageWebhook":     "yes",
        "outgoingAPIMessageWebhook":  "yes",
        "pollMessageWebhook":         "yes",
        "markIncomingMessagesReaded": "yes",
    })

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

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

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

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

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

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

3. Настройка чатбота#

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

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

case "2":
    message.AnswerWithUrlFile(
        "https://images.rawpixel.com/image_png_1100/cHJpdmF0ZS9sci9pbWFnZXMvd2Vic2l0ZS8yMDIzLTExL3Jhd3BpeGVsb2ZmaWNlMTlfcGhvdG9fb2ZfY29yZ2lzX2luX2NocmlzdG1hc19zd2VhdGVyX2luX2FfcGFydF80YWM1ODk3Zi1mZDMwLTRhYTItYWM5NS05YjY3Yjg1MTFjZmUucG5n.png",
        "corgi.png",
        util.GetString([]string{"send_file_message", lang})+util.GetString([]string{"links", lang, "send_file_documentation"}))

Добавьте ссылку на файл любого расширения в качестве первого параметра метода answerWithUrlFile и задайте имя файлу во втором параметре. Имя файла должно содержать расширение, например "somefile.pdf". Данная строка после изменения будет в следующем формате:

case "2":
    message.AnswerWithUrlFile(
        "https://...somefile.pdf",
        "somefile.pdf",
        util.GetString([]string{"send_file_message", lang})+util.GetString([]string{"links", lang, "send_file_documentation"}))

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

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

Если предыдущие шаги были выполнены, то на вашем аккаунте Whatsapp должен работать чатбот. Важно помнить, что пользователь должен быть авторизован в личном кабинете.

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

Чатбот откликнется на любое сообщение отправленное на аккаунт. Так как чатбот поддерживает несколько языков - то прежде чем поприветствовать собеседника, чатбот попросит выбрать язык общения:

1 - English
2 - Қазақша
3 - Русский
...

Ответьте цифрой 1, 2 или 3, чтобы выбрать язык для дальнейшего общения. После того как вы отправите 3, чатбот пришлет приветственное сообщение на русском языке:

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

1. Текстовое сообщение 📩
2. Файл 📋
3. Картинка 🖼
4. Аудио 🎵
5. Видео 📽
6. ...

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

Выбрав число из списка и отправив его, чатбот ответит каким API был отправлен данный тип сообщения и поделится ссылкой на информацию об API.

Например, отправив 1, пользователь получит в ответ:

Это сообщение отправлено через метод sendMessage.

Чтобы узнать как работает метод, пройдите по ссылке
https://green-api.com/docs/api/sending/SendMessage/

Если отправить что-то помимо чисел 1-13, то чатбот лаконично ответит:

Извините, я не совсем вас понял 😔, напишите меню, чтобы посмотреть возможные опции

Так же пользователь может вызвать меню, отправив сообщение содержащее "меню". И отправив "стоп", пользователь завершит беседу с чатботом и получит сообщение:

Спасибо за использование чатбота GREEN-API, пользователь!

5. Структура кода#

Основной файл чатбота это main.go, в нем находится функция main и с него начинается выполнение программы. В этом классе происходит инициализация объекта бота при помощи класса BotFactory, установка первой сцены и запуск бота.

func main() {
    bot := chatbot.NewBot(idInstance, apiTokenInstance)      //Инициализация бота с параметрами INSTANCE и TOKEN из констант

    go func() {                                         //Обработка ошибок
        for err := range bot.ErrorChannel {
            if err != nil {
                log.Println(err)
            }
        }
    }()

    if _, err := bot.GreenAPI.Methods().Account().SetSettings(map[string]interface{}{      //Установка настроек инстанса
        "incomingWebhook":            "yes",
        "outgoingMessageWebhook":     "yes",
        "outgoingAPIMessageWebhook":  "yes",
        "pollMessageWebhook":         "yes",
        "markIncomingMessagesReaded": "yes",
    }); err != nil {
        bot.ErrorChannel <- err
    }   

    bot.SetStartScene(scenes.StartScene{})      //Установка стартовой сцены бота

    bot.StartReceivingNotifications()       //Запуск бота
}

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

Для каждого чата одновременно активна может быть только одна сцена.

Например, первая сцена start.go отвечает за приветственное сообщение. Вне зависимости от текста сообщения, бот спрашивает какой язык удобен пользователю и включает следующую сцену, которая отвечает за обработку ответа.

Всего в боте 4 сцены:

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

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

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

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

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

Что касается получения сообщений, то сообщения вычитываются через HTTP API. Документация по методам получения сообщений.

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

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

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

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

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