How to manage state and scenes#

Installation#

Before you begin, you need to install the library and configure the bot; this process is described in detail here: How to import the library and configure your bot.

How to manage scenes#

There are special methods in the Scene class to manage scenes. They must be executed after the return keyword inside the active scene method. These methods change the current scene parameter in the chat state, the next message received from this chat will go into a new scene.

Methods of the `Scene` class	Описание
`activateNextScene(State currentState, Scene nextScene)`	Activates the next `nextScene` for the current chat.
`activateStartScene(State currentState)`	Activates the start scene for the current user.

Full list of scene methods:#

Methods of `Scene.class`	Description
`activateNextScene(State currentState, Scene nextScene)`	Activates the next `nextScene` for the current chat.
`activateStartScene(State currentState)`	Activates the start scene for the current user.
`getText(MessageWebhook messageWebhook)`	Returns the text of the message if it is text, otherwise returns `null`
`answerWithText(MessageWebhook messageWebhook, String text)`	Replies with text to an incoming message.
`answerWithUploadFile(MessageWebhook messageWebhook, String caption, File file)`	Downloads and sends a file in response to an incoming message. `Caption` is an optional field.
`answerWithUrlFile(MessageWebhook messageWebhook, String caption, String url, String fileName)`	Sends a file from a url in response to an incoming message. `Caption` is an optional field.
`answerWithLocation(MessageWebhook messageWebhook, String nameLocation, String address, Double latitude, Double longitude)`	Sends geolocation in response to an incoming message.
`answerWithPoll(MessageWebhook messageWebhook, String message, List<Option> options, Boolean multipleAnswers)`	Sends a survey in response to an incoming message.
`answerWithContact(MessageWebhook messageWebhook, Contact contact)`	Sends a contact in response to an incoming message.

In the overloaded version, message response methods may contain additional expectedMessage parameters and regexPattern, if the text of the incoming message matches the condition, the method will be executed and return the method response according to the documentation; if not, the method will return null.

How to manage user state#

To manage the user's state, just make changes to the currentState object inside the scene and return it using return or passing it to one of the scene methods. At the end of each scene, the state is automatically updated.

To manage the state directly, you need to use the stateManager object which is an instance of your implementation of the StateManager interface. This object is available in any scene, as it is one of its fields. The manager has methods that perform basic crud operations on the state. You also have the option to save chat data in its state.

Manager method	Description
`get()`	Returns the state of the selected chat.
`create()`	Creates a new state for chat.
`update()`	Updates the state (the method is not present in the default implementation of the interface)
`delete()`	Removes the user's state.
`getStateData()`	Returns state data
`setStateData()`	If the state exists, overwrites the state data
`updateStateData()`	If the state exists, updates the state data (put)
`deleteStateData()`	If the state exists, then clears the state data (sets default values)

The state identifier is the chat ID (the chatId field, not to be confused with senderId).

As an example, a bot was created for user registration consisting of 3 scenes. Start, username entry scene and password entry scene.

Link to example: 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;
    }
}

List of examples#

Description	Example link
How to initialize an object	BotStarterClassExample.java
Scene "Hello"	BaseStartScene.java
Scene "Echo"	EchoStartScene.java
How to receive other types of notifications	EventStartScene.java
How to filter incoming messages	FiltersStartScene.java
How to handle notification body	MediaStartScene.java
How to work with bot state	state
Example of a ready-made chat-bot	full