Как управлять состоянием и сценами#

Установка#

Перед началом необходимо установить библиотеку и сконфигурировать бота, подробно этот процесс описан здесь: Как импортировать библиотеку и сконфигурировать своего бота.

Как управлять сценами#

Для управления сценами в классе Scene есть специальные методы. Их необходимо выполнять после ключевого слова return внутри метода активной сцены. Данные методы меняют текущий параметр scene в состоянии чата, следующее сообщение полученное из этого чата, попадет в новую сцену.

Методы класса `Scene`	Описание
`activateNextScene(State currentState, Scene nextScene)`	Активирует следующую сцену `nextScene` для текущего чата.
`activateStartScene(State currentState)`	Активирует стартовую сцену для текущего пользователя.

Полный перечень методов сцены:#

Методы класса `Scene`	Описание
`activateNextScene(State currentState, Scene nextScene)`	Активирует следующую сцену `nextScene` для текущего чата.
`activateStartScene(State currentState)`	Активирует стартовую сцену для текущего пользователя.
`getText(MessageWebhook messageWebhook)`	Возвращает текст сообщения, если оно текстовое, если нет возвращает `null`
`answerWithText(MessageWebhook messageWebhook, String text)`	Отвечает текстом на входящее сообщение.
`answerWithUploadFile(MessageWebhook messageWebhook, String caption, File file)`	Загружает и отправляет файл в ответ на входящее сообщение. `Сaption` - не обязательное поле.
`answerWithUrlFile(MessageWebhook messageWebhook, String caption, String url, String fileName)`	Отправляет файл из url в ответ на входящее сообщение. `Сaption` - не обязательное поле.
`answerWithLocation(MessageWebhook messageWebhook, String nameLocation, String address, Double latitude, Double longitude)`	Отправляет геолокация в ответ на входящее сообщение.
`answerWithPoll(MessageWebhook messageWebhook, String message, List<Option> options, Boolean multipleAnswers)`	Отправляет опрос в ответ на входящее сообщение.
`answerWithContact(MessageWebhook messageWebhook, Contact contact)`	Отправляет контакт в ответ на входящее сообщение.

В перегруженном варианте методы ответов на сообщения могут содержать дополнительные параметры expectedMessage и regexPattern, если текст входящего сообщения совпадает с условием, метод выполнится и вернет ответ метода согласно документации, если нет, то метод вернет null.

Как управлять состоянием пользователя#

Чтобы управлять состоянием пользователя, достаточно внести изменения в объект currentState внутри сцены и вернуть его с помощью return или передать в один из методов сцены. В конце каждой сцены происходит автоматическое обновление состояния.

Для управления состоянием напрямую нужно использовать объект stateManager который является инстансом вашей имплементацией интерфейса StateManager. Данный объект доступен в любой сцене, так как является одним из ее полей. В менеджере есть методы которые совершают основные crud операции над состоянием. Также у вас есть возможность сохранить данные чата в его состоянии.

Метод менеджера	Описание
`get()`	Возвращает состояние выбранного чата.
`create()`	Создает новое состояние для чата.
`update()`	Обновляет состояние (в дефолтной реализации интерфейса метод не представлен)
`delete()`	Удаляет состояние пользователя.
`getStateData()`	Возвращает данные состояния
`setStateData()`	Если состояние существует, перезаписывает данные состояния
`updateStateData()`	Если состояние существует, обновляет данные состояния (put)
`deleteStateData()`	Если состояние существует, то очищает данные состояния (устанавливает дефолтные значения)

Идентификатором состояния является ID чата (поле chatId, не путать с senderId).

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

Ссылка на пример: state.

public class StateStartScene extends Scene {
    @Override
    public State processIncomingMessage(MessageWebhook incomingMessage, State currentState) {
        answerWithText(incomingMessage, "Hello. Tell me your username.");

        return activateNextScene(currentState, new InputUsernameScene());
    }
}

public class InputUsernameScene extends Scene {
    @Override
    public State processIncomingMessage(MessageWebhook incomingMessage, State currentState) {
        var stateData = currentState.getData();

        var username = getText(incomingMessage);
        if (username != null && username.length() <= 20 && username.length() >= 5) {
            stateData.put("username", username);
            currentState.setData(stateData);

            answerWithText(incomingMessage, "Please, send password");

            activateNextScene(currentState, new InputPasswordScene());

        } else {
            answerWithText(incomingMessage, "invalid username");
        }

        return currentState;
    }
}

public class InputPasswordScene extends Scene {
    @Override
    public State processIncomingMessage(MessageWebhook incomingMessage, State currentState) {
        var stateData = currentState.getData();

        var password = getText(incomingMessage);
        if (password != null && password.length() <= 20 && password.length() >= 8) {
            stateData.put("password", password);
            currentState.setData(stateData);

            answerWithText(incomingMessage, String.format("""
                Successful account creation.
                Your username: %s.
                Your password: %s.
                """, stateData.get("username"), password));

            return activateStartScene(currentState);

        } else {
            answerWithText(incomingMessage, "invalid password");
        }

        return currentState;
    }
}

Список примеров#

Описание	Ссылка на пример
Как инициализировать объект	BotStarterClassExample.java
Сцена "Привет"	BaseStartScene.java
Сцена "Эхо"	EchoStartScene.java
Как получать другие типы уведомлений	EventStartScene.java
Как фильтровать входящие сообщения	FiltersStartScene.java
Как обрабатывать тело уведомлений	MediaStartScene.java
Как работать с состоянием бота	state
Пример готового чат бота	full