ConversationConfig
Configuration options for a conversation. These options can be passed to create
Properties
id
id?: string;
Identifier of the conversation. The identifier can be used to enter or exit conversations from middleware.
Defaults to the JavaScript function name.
plugins
plugins?: Middleware<C>[];
An array of plugins to be installed on every context object created by the conversation.
Remember that when a conversation is executed, it creates a number of context objects from scratch during each replay. If this is not obvious to you, it means that you probably should read the documentation of this plugin in order to avoid common pitfalls.
The created context objects did not pass through the middleware tree, so they will not have any properties installed on them. You can use this configuration option to specify a number of grammY plugins that should receive each context object created by the conversation.
This lets you use many plugins inside the conversation. However, there are still a few things to be aware of. In a typical middleware pass, every plugin can process a context object, then call next
to wait for downstream middleware to finish, and then get the opportunity to perform cleanup tasks or execute other code after the update was processed downstream.
Passing middleware to the plugins
array will behave differently in the sense that a call to next
will resolve immediately. The context object is given to the conversation only after all plugins have processed it. Plugins that depend on executing tasks after calling next
therefore will not work correctly.
If a plugin decides to fully handle an update by not calling next
, then this will consume the update. Any pending wait
calls inside the conversation will only receive the next incoming update.
Note that you can install Bot API transformers from inside middleware, too. This lets you modify the instances of Api
created by the conversations plugin.
plugins: [async (ctx, next) => {
ctx.api.config.use(transformer)
await next()
}]
In some cases, TypeScript is known not to be able to infer the correct context type for plugins passed to this configuration option. The types are still checked, though, which leads to compilation errors. They can be fixed by passing the custom context type to the plugins explicitly. Note that you need to use the custom context type used inside the conversation, not the custom context type used in the outside middleware.
maxMillisecondsToWait
maxMillisecondsToWait?: number;
Specifies a default timeout for all wait calls inside the conversation.
This value can be overridden for each wait call by passing a different timeout value.
parallel
parallel?: boolean;
Marks the conversation as parallel.
By default, only a single conversation can ben active per chat. When this option is set to true
, this conversation can be entered when a different conversation with the same or a different identifier is already active. For example, in a single group chat, you can have 10 different active conversations with 10 different users all at the same time.
Conversations from different chats are always parallel.
Only a single conversation can handle an update. When multiple conversations are active at the same time in a chat, only the first conversation will receive the update. If it decides to skip the update, the second conversation will receive the update. This order is determined by the order in which the different conversations are installed in the middleware tree. If multiple conversations with the same identifer are active, they will recieve the update in chronological order of the time that the conversations were entered.
By default, when a conversation decides to skip an update, the update will be dropped. When a conversation is marked as parallel, it will default to returning the update to the middleware system so that other active conversations can pick up the update and handle it. This also means that if you mark a conversation as parallel, unrelated downstream middleware might process the update.
When an update is skipped, an option next
can be passed to override the above behavior. This lets you decide for every call to skip
whether parallel conversations as well as other middleware shall receive an update, or whether the update should be dropped. The same option exists for filtered wait calls, chained wait calls, and conversational forms.
Defaults to false
.