ConversationPlugin<CTX extends Context> class

A conversation management plugin that allows waiting for user updates with timeout support.

This plugin provides the ability to create conversations that can wait for user input and maintain state across multiple updates. Each conversation can pause execution and resume when the next update arrives. The plugin includes automatic cleanup of expired conversations to prevent memory leaks.

Example usage:

// Define a conversation function
Future<void> askName(Conversation<Context> conversation, Context ctx) async {
  try {
    await ctx.reply('What is your name?');
    final nameCtx = await conversation.wait(Duration(minutes: 5));
    await nameCtx.reply('Hello ${nameCtx.text}!');
  } on ConversationTimeoutException {
    await ctx.reply('Sorry, you took too long to respond.');
  }
}

// Install the plugin and register the conversation
final conversationPlugin = ConversationPlugin<Context>(
  defaultTimeout: Duration(minutes: 30),
  cleanupInterval: Duration(minutes: 5),
);
bot.plugin(conversationPlugin);
bot.use(createConversation('askName', askName));

// Start the conversation
bot.command('start', (ctx) async {
  await ctx.conversation.enter('askName');
});
Implemented types

Constructors

ConversationPlugin.new({ConversationStorage? storage, String getStorageKey(CTX ctx)?, Duration defaultTimeout = const Duration(minutes: 30), Duration cleanupInterval = const Duration(minutes: 5), void onConversationExpired(String conversationName, String key)?, Future<void> onConversationTimeout(String conversationName, CTX? ctx)?})
Creates a conversation plugin.

Properties

cleanupInterval Duration
Interval for automatic cleanup of expired conversations.
final
defaultTimeout Duration
Default timeout for conversations.
final
dependencies List<String>
List of plugin names that this plugin depends on.
no setteroverride
description String
Optional description of what this plugin does.
no setteroverride
getStorageKey String Function(CTX ctx)
Function to generate storage keys from context.
final
hashCode int
The hash code for this object.
no setterinherited
name String
The unique name of this plugin.
no setteroverride
onConversationExpired → void Function(String conversationName, String key)?
Callback called when a conversation expires.
final
onConversationTimeout Future<void> Function(String conversationName, CTX? ctx)?
Callback called when a conversation times out during wait.
final
runtimeType Type
A representation of the runtime type of the object.
no setterinherited
storage ConversationStorage
Storage for conversation state.
final
version String
The version of this plugin.
no setteroverride

Methods

cleanupExpiredConversations() Future<void>
Manually cleans up expired conversations.
enterConversation(String conversationName, CTX ctx) Future<void>
Starts a conversation by name.
forceCleanupConversation(String key) Future<void>
Forces cleanup of a specific conversation.
getActiveConversations() Future<List<String>>
Gets a list of all active conversation keys.
getConversationStats() Future<ConversationStats>
Gets statistics about active conversations.
install(Bot<CTX> bot) → void
Installs the plugin on the given bot.
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
registerConversation(String name, ConversationFunction<CTX> conversationFn) → void
Registers a conversation function.
setConversationTimeout(String key, Duration timeout) Future<void>
Sets a custom timeout for a specific conversation.
toString() String
A string representation of this object.
inherited
uninstall(Bot<CTX> bot) → void
Uninstalls the plugin from the given bot.
override

Operators

operator ==(Object other) bool
The equality operator.
inherited

Static Properties

instance ConversationPlugin<Context>?
Legacy getter for backwards compatibility.
no setter

Static Methods

getInstance<T extends Context>() ConversationPlugin<T>?
Gets the current plugin instance.