ConversationControls

^{ref / conversations / ConversationControls}

A control panel for all known conversations. This holds the enter method that is the main entrypoint to a conversation.

In addition, conversations can be killed from the outside using one of the exit methods.

Finally, the control panel can be used to inspect which conversations are currently active.

^Source

Methods

enter

enter(name: string, ...args: unknown[]): Promise<void>;

Enters the conversation with the given identifer. By default, the name of the function is the identifier of the function. You can override this value when calling createConversation.

// Enters a conversation called "convo" upon a start command.
bot.command("start", async ctx => {
  await ctx.conversation.enter("convo")
})

Entering a conversation will make the conversation run partially until the first wait call is reached. The enter call will therefore return long before the conversation has returned.

You can pass any number of arguments when entering a conversation. These arguments will be serialized to JSON and persisted in the storage as string. Whenever the conversation is replayed, this string is parsed back to objects and supplied to the conversation. This means that all arguments must be JSON-serializable.

// Enters a conversation called "convo" upon a start command.
bot.command("start", async ctx => {
  await ctx.conversation.enter("convo", 42, "cool", { args: [2, 1, 0] })
})
async function convo(conversation, ctx, num, str, { args }) {
  // ...
}

Be careful: There is no type safety for conversation arguments! You must annotate the correct types in the function signature of the conversation builder function, and you also have to make sure that you pass matching values to enter.

This method will throw an error if the same or a different conversation has already been entered. If you want to enter a conversations in parallel to existing active conversations, you can mark it as parallel. This can be done by passig { parallel: true } to createConversation.

^Source

exit

exit(name: string): Promise<void>;

Purges all state of the conversation with the given identifer for the current chat. This means that if the specified conversation had been active, it is now terminated. If the conversation was marked as parallel, all conversations with this identifier are left for the current chat.

Note that if you call this method concurrently to a replay, the replay will not be interrupted. However, its data will not be saved as soon as the replay finishes.

For every exited conversation, onExit will be called if specified when installing the conversations plugin.

Does nothing if no conversation with the given name is active in the current chat.

^Source

exitAll

exitAll(): Promise<void>;

Purges all state of all conversations in the current chat, irrespective of their identifers. This will terminate all conversations.

Note that if you call this method concurrently to a replay, the replay will not be interrupted. However, its data will not be saved as soon as the replay finishes.

For every exited conversation, onExit will be called if specified when installing the conversations plugin.

Does nothing if no conversations are running.

^Source

exitOne

exitOne(name: string, index: number): Promise<void>;

Purges all state of the conversation with the given identifer at the given position for the current chat. This means that if the specified conversation had been active, it is now terminated. The position is determined chronologically. For example, passing 0 will exit the oldest parallel conversation with the given identifier that is still active.

Note that if you call this method concurrently to a replay, the replay will not be interrupted. However, its data will not be saved as soon as the replay finishes.

onExit will be called if specified when installing the conversations plugin.

Does nothing if no conversation with the given name is active at the given position in the current chat.

^Source

active

// Overload 1
active(): Record<string, number>;

Returns an object specifying the number of times that each conversation is currently active. For example, if a parallel conversation called “captcha” is active 3 times in the current chat, and a conversation called “settings” is active once in the same chat, the returned object will look like this.

{
  captcha: 3,
  settings: 1,
}

^Source