Conversation

Overview

A Conversation is the FSM (remember the example?), you have to define all the connections between the State.
In addition, you can set a fallback State in case of errors and an authorized users list.

Basic

With the add_routes function you will set the routes (connections) for a State: routes define where a State will go (map the index with the index of the keyboard buttons), a default State to go in all other cases and a back State for the back button.

Doc

Usage example: conversation.py

Conversation(
    start_state: State,
    end_state: Optional[State] = None,
    fallback_state: Optional[State] = None,
    state_messages: Optional[Union[str, Mapping[str, str]]] = None
)

• start_state: first state of the conversation.
• end_state: final state of the conversation.
• fallback_state: fallback handler state of the conversation (if defined, the conversation handle an error in this state).
• state_messages: a dictionary (can be a file JSON, YAML or TOML) with text messages for states in the conversation. Check the Texts Guide for more info.

Add Routes

Usage example: conversation.py

# define the routes for a state in the conversation (automatically added to conversation)
Conversation.add_routes(
    state: State,
    routes: Optional[dict] = None,
    default: Optional[State] = None,
    back: Optional[State] = None
)

• state: initial state of the ruote.
• routes: routes where a state should go for every possibile data received.
• default: default route if value isn't in ruotes.
• back: route to go when the back button is pressed, if exists. If the state isn't specified and the starting state has a back button, it'll go to back the previous state.

Set Defaults

Usage example: defaults.py

# define default values, a function applied to text and a back button for every States in the conversation
Conversation.set_defaults(
    params: Optional[dict] = None,
    func: Optional[Callable] = None,
    back_button: Optional[str] = None,
)

• params: kwargs with every parameters you need from Telegram API sendMessage.
• function: default function applied to every State text.
• back_button: default back button for every State.

Add Authorized Users

Usage example: authorization.py

# define a list of users able to access this conversation and an optional fallback State
Conversation.add_authorized_users(
    users_list: Sequence[int],
    no_auth_state: State
)

• users_list: list of users (Telegram ID) able to access the conversation.
• no_auth_state: state in which unauthorized users end up.

Get State

# get a states by name in the conversation
Conversation.get_state(
    state_name: str
)

• state_name: a state name to search in the conversation.