GREEN-API Java demo chatbot#

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

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

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

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

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

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

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

Чтобы запустить проект вам понадобиться любая IDE. Откройте ваш редактор кода и создайте новый проект из системы контроля версий. Для этого нажмите file - new - Project from Version Control System. В открывшимся окне введи адрес проекта:

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

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

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

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

idInstance
apiTokenInstance

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

var bot = botFactory.createBot(
    "{{INSTANCE}}",
    "{{TOKEN}}");

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

mvn clean install exec:java -Dexec.mainClass=com.greenapi.demoChatbot.BotStarter
или
./mvnw spring-boot:run

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

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

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

    bot.greenApi.account.setSetting(InstanceSettingsReq.builder()
            .incomingWebhook("yes")
            .outgoingMessageWebhook("yes")
            .outgoingAPIMessageWebhook("yes")
            .pollMessageWebhook("yes")
            .markIncomingMessagesReaded("yes")
            .build());

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

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

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

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

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

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

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

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

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

case "2" -> {
answerWithUrlFile(incomingMessage, 
    YmlReader.getString(new String[]{"send_file_message", lang.getValue()}) +
    YmlReader.getString(new String[]{"links", lang.getValue(), "send_file_documentation"}),
    "https://images.rawpixel.com/image_png_1100/cHJpdmF0ZS9sci9pbWFnZXMvd2Vic2l0ZS8yMDIzLTExL3Jhd3BpeGVsb2ZmaWNlMTlfcGhvdG9fb2ZfY29yZ2lzX2luX2NocmlzdG1hc19zd2VhdGVyX2luX2FfcGFydF80YWM1ODk3Zi1mZDMwLTRhYTItYWM5NS05YjY3Yjg1MTFjZmUucG5n.png",
    "corgi.pdf",
    false);
    return currentState;

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

case "2" -> {
    answerWithUrlFile(incomingMessage, 
        YmlReader.getString(new String[]{"send_file_message", lang.getValue()}) +
        YmlReader.getString(new String[]{"links", lang.getValue(), "send_file_documentation"}),
        "https://...somefile.pdf",
        "somefile.pdf",
        false);
    return currentState;

Все изменения должны быть сохранены, после чего можно запускать чатбот. Для запуска чатбота вернитесь к пункту 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. Структура кода#

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

public static void main(String[] args) {
    var context = SpringApplication.run(BotStarter.class, args); //Инициация контекста Spring приложения
    var botFactory = context.getBean(BotFactory.class);          //Импорт BotFactory bean из контекста

    var bot = botFactory.createBot(                             //Инициализация бота с параметрами INSTANCE и TOKEN
    "{{INSTANCE}}",
    "{{TOKEN}}");

    bot.setStartScene(new Start());                             //Установка стартовой сцены бота

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

Класс BotFactory это Bean который сконфигурирован в BotConfig. Его задача создать объект бота. В конфигурации BotConfig вы можете более тонко настроить класс RestTemplate для отправки запросов или подставить свою имплементацию StateManager если она у вас есть. В данном примере BotConfig использует стандартные, рекомендованные значения по умолчанию.

@Configuration
public class BotConfig {

    @Bean
    public RestTemplate restTemplate() {         //Стандартный Spring класс для отправки http запросов. 
        return new RestTemplateBuilder().build();
    }

    @Bean
    public StateManager stateManager() {         //StateManager - интерфейс для работы с состоянием. 
        return new StateManagerHashMapImpl();    //StateManagerHashMapImpl его стандартная реализация. Вы можете написать свою и подставить если вы не хотите хранить данные в hashmap.
    }

    @Bean
    public BotFactory botFactory(RestTemplate restTemplate, StateManager stateManager) {   //BotFactory bean для инициализации объекта бота
        return new BotFactory(restTemplate, stateManager);
    }
}

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

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

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

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

Сцена Start - отвечает на любое входящее сообщение, отправляет список доступных языков. Запускает сцену MainMenu.
Сцена MainMenu - обрабатывает выбор пользователя и отправляет текст главного меню на выбранном языке. Запускает сцену Endpoints
Сцена Endpoints - выполняет выбранный пользователем метод и отправляет описание метода на выбранном языке.
Сцена CreateGroup - cцена создает группу, если пользователь сказал, что добавил бота в свои контакты (1). Если нет (0), возвращается к сцене «Endpoints».

Класс SessionManager содержит метод isSessionExpired который возвращает true если пользователь не пишут боту более 2 минут. Он используется, чтобы снова устанавливать стартовую сцену, если боту долго не пишут.

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

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

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

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

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

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

    answerWithText(incomingMessage, YmlReader.getString(new String[]{"select_language"}));

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

    greenApi.service.getAvatar(incomingMessage.getSenderData().getChatId());