Interface ConversationManager

public sealed interface ConversationManager

Manages conversations within the bot.

This interface provides methods for registering, removing, joining, leaving, and querying conversations. It includes support for custom properties and constraint checks for managing conversation instances.

  • Method Details

    • newConversationManager

      @Internal @NotNull static @NotNull ConversationManager newConversationManager(@NotNull @NotNull TelegramBot bot)

    • registerConversation

      void registerConversation(@NotNull @NotNull Conversation conversation)
      Registers a new conversation.
      Parameters:
      conversation - The Conversation to be registered. It should be a valid, non-null instance implementing the Conversation interface.
      Throws:
      NullPointerException - if the conversation is null.

    • removeConversation

      void removeConversation(@NotNull @NotNull String conversationName)
      Removes an existing Conversation.
      Parameters:
      conversationName - The name of the Conversation to be removed. This should match the name returned by Conversation.name().
      Throws:
      NullPointerException - if the conversation name is null.
      IllegalArgumentException - if the conversation does not exist.

    • joinConversation

      ConversationManager.JoinResult joinConversation(@NotNull @NotNull User user, @NotNull @NotNull Chat chat, @NotNull @NotNull String conversationName)
      Allows a user to join a registered conversation in a specified chat.
      Parameters:
      user - The User who is joining the Conversation.
      chat - The Chat where the conversation is taking place.
      conversationName - The name of the Conversation the user wants to join. This should match the name returned by Conversation.name().
      Returns:
      A ConversationManager.JoinResult indicating the result of the join operation.
      Throws:
      IllegalArgumentException - if either a required property is missing or an unknown property is passed when allowUnknownProperties is false.

    • joinConversation

      ConversationManager.JoinResult joinConversation(@NotNull @NotNull User user, @NotNull @NotNull Chat chat, @NotNull @NotNull String conversationName, @Nullable @Nullable Map<String,Object> properties)
      Allows a user to join a registered conversation in a specified chat with custom properties.
      Parameters:
      user - The User who is joining the Conversation.
      chat - The Chat where the conversation is taking place.
      conversationName - The name of the Conversation the user wants to join. This should match the name returned by Conversation.name().
      properties - A list of custom properties to be passed to the conversation. This can be used to pass additional information to the conversation.
      Returns:
      A ConversationManager.JoinResult indicating the result of the join operation.
      Throws:
      IllegalArgumentException - if either a required property is missing or an unknown property is passed when allowUnknownProperties is false.

    • leaveConversation

      void leaveConversation(@NotNull @NotNull User user)
      Allows a user to forcefully leave an active conversation. This can be useful in cases where the bot needs to remove the user from the conversation for any reason.
      Parameters:
      user - The User who is leaving the conversation.
      Throws:
      IllegalStateException - if the user is not in a conversation.

    • isUserInConversation

      boolean isUserInConversation(@NotNull @NotNull User user)
      Checks whether a user is currently participating in a specific conversation.
      Parameters:
      user - The user to check.
      Returns:
      True if the user is currently part of the specified conversation, false otherwise.

    • getConversations

      @NotNull @NotNull @Unmodifiable Collection<Conversation> getConversations()
      Returns an unmodifiable collection of all registered conversations. This collection includes all conversations that have been registered, regardless of whether they are currently active.
      Returns:
      An unmodifiable collection of all registered Conversations.

    • getConversation

      @Nullable @Nullable Conversation getConversation(@NotNull @NotNull String conversationName)
      Retrieves a specific conversation by its name.
      Parameters:
      conversationName - The name of the Conversation to retrieve. This should match the name returned by Conversation.name().
      Returns:
      The Conversation corresponding to the given name, or null if no such conversation is registered.

    • getRunningConversations

      @NotNull @NotNull @Unmodifiable Collection<ConversationContext> getRunningConversations()
      Returns an unmodifiable collection of all currently active conversations.
      Returns:
      An unmodifiable collection of all running ConversationContexts, representing the active instances of conversations.