@IlyaSemenov sorry for the long delay. I did not have much time for this in past few months, and also I started having more and more doubts about this. I have concluded that my idea above is bad. You are right. We have already talked about some of the disadvantages here, and I thought of several more, which I will skip now.

Thanks for your work on scenes, I appreciate it! This is great, it is probably the best implementation of scenes that I’ve seen so far. I found your observations especially valuable. It’s cool to see that composition and nesting based around a concept of waiting and resuming is well-suited. However, I did not change my mind about scenes in general. I still can’t read the code in a linear fashion (because every step has a different callback), and I have to know a lot about the plugin to make sense of what all the GOTO jumping does. This still interrupts the reading flow all the time.

This is why I created a new package with a completely different strategy than discussed at any point before. It is very much not usable yet, but there is an example bot in the README which outlines the concept. It can do the wait/resume thing, supports nesting, loops, functions, branching, recursion, error-handling with try-catch-finally, composition across modules, and so on. (We basically get all of this for free, it does not need to be supported explicitly.) It is trivial to implement the system you talked about which lets you resume based on external events (but I wanted to publish before adding that, so it’s not supported yet). It has type safe local sessions, even across functions, and the code is more concise than any of the ideas discussed above. Also, it is very easy to understand the code even if you have never seen the package before.

Naturally, there are a few pitfalls. The main thing is that side-effects outside of grammY must be wrapped in function calls. Basically, you can communicate with the user and do everything with the Bot API, but external things which perform side-effects or are non-deterministic must be wrapped in another function call. Some people may know this pattern from React, there is is called useEffect. It is not pretty, so it must be documented well, but it is a known thing and I think people will cope with it.

I published the (unfinished) code at https://github.com/grammyjs/conversations.

Thank you for brainstorming here! I will close this issue now. There will be more things to talk about, but they are going to be specific to conversations, so they can be discussed in new issues in the new repository.

I hope you give this thing a try, I’d be looking forward to your feedback and criticism!

Approach C: “Wait and Resume”

On first sight, this suggestion may look similar to Approach A. However, it actually behaves very differently and it makes more sense to start explaining it from scratch.

Remember from https://grammy.dev/advanced/middleware that middleware is a tree in grammY. This tree will be traversed in depth-first order.

We regard a conversation also as a hierarchy of different flows. Always start with question Q0, if the user says YES, continue with Q1, else continue with Q2.

We suggest to use the former hierarchy to express the latter.

Here is the example from the top again. Handling invalid input is omitted intentionally for brevity.

const conversation = new Conversation('age-at-birth')

conversation.command('start', async ctx => {
  await ctx.reply('How old are you'))
  ctx.conversation.resume()
})

conversation.wait()

conversation.on('message:text', async ctx => {
  ctx.session.age = parseInt(ctx.msg.text, 10)
  await ctx.reply('Cool, how old is your mother?')
  ctx.conversation.resume()
})

conversation.wait()

conversation.on('message:text', async ctx => {
  const age = parseInt(ctx.msg.text, 10)
  await ctx.reply(`Alright, she was ${age - ctx.session.age} when you were born!`)
  ctx.conversation.leave()
})

This provides a simple linear flow that could be illustrated by

O
|
O
|
O

We can interrupt the middleware execution by inserting a wait call. We can call resume to continue traversing the middleware tree. In a way, calling ctx.conversation.resume is like calling next in the traditional middleware tree. (Please leave a comment if you think the method should be renamed to ctx.conversation.next in order to display this similarity.)

The wait calls optionally take string identifiers if you want to jump to a specific point, rather than only resuming after the next wait call.

Next, let us see how we can branch out, and have an alternative way of continuing the conversation.

const conversation = new Conversation('age-at-birth')

conversation.command('start', async ctx => {
  await ctx.reply('How old are you'))
  ctx.conversation.resume()
})

conversation.wait()

// start a new sub-conversation
const invalidConversation = conversation.filter(ctx => isNaN(parseInt(ctx.msg?.text ?? '')))
invalidConversation.on('message', ctx => ctx.reply('That is not a number, so I will assume you sent me the name of your pet. What animal is it?'))
invalidConversation.wait()
// TODO: continue conversation about pets here

// Go on with regular conversation about age:
conversation.on('message:text', async ctx => {
  ctx.session.age = parseInt(ctx.msg.text, 10)
  await ctx.reply('Cool, how old is your mother?')
  ctx.conversation.resume()
})
conversation.wait()

conversation.on('message:text', async ctx => {
  const age = parseInt(ctx.msg.text, 10)
  await ctx.reply(`Alright, she was ${age - ctx.session.age} when you were born!`)
  ctx.conversation.leave()
})

We have now defined a conversation that goes like this:

O
| \
O  O
|
O

That way, we can define conversation flows.

Note that the conversation will remain between two wait calls until you explicitly call ctx.conversation.resume. It may be desirable to let the conversation resume automatically, and instead let people remain explicitly. Here is how that could work:

const conversation = new Conversation('word-of-the-year', { autoResume: true })

conversation.on('message', async ctx => {
  await ctx.reply('What is your favourite English word?))
})
conversation.wait()
conversation.on('message', async ctx => {
  ctx.session.word = ctx.msg.text
  await ctx.reply('Why do you want this word to become the word of the year?'))
})
conversation.wait()
conversation.on('message', async ctx => {
  ctx.session.reason = ctx.msg.text
  await ctx.reply('Is there anything else you would like to say?'), {
    reply_markup: new InlineKeyboard().text('Nope', 'no')
  })
})
conversation.wait()
conversation.on('message', async ctx => {
  ctx.session.comment = ctx.msg.text
  await ctx.reply('Thank you for you submission'))
})
conversation.callbackQuery('no', ctx => ctx.reply('Skipped. Thanks for the submission!'))

Personally, I think this is so far the best option we have. I prefer it over the other two approaches. What do you think?

I kind of implemented “nested handlers” approach in https://github.com/IlyaSemenov/grammy-scenes

I’ve extracted it to a npm package from one of my actual bot projects.

I am not 100% happy with the API and architecture I ended up with, but it allows to write concise code, while still being quite flexible (it extends the built-in Composer class, thus allowing to fallback to generic scene.use(...) for advanced middleware use cases).

One of the things I’m not sure in is handling the scenes context. I’m not convinced whether scenes should have separate first-class contexts, or if we should simply direct user to use “normal” sessions for their context data. In my initial prototypes I went with the former, which (back then) resulted in very complex Typescript generics, and it also wasn’t straightforward when to clear the context and when to keep it. So I ditched all that in favour of “normal” sessions with some simple typings (see example in README) — but I’m not exactly happy about that. First class scene contexts still seem to be a better fit to me, they just need to be carefully implemented.

How to conditionally skip a step?

Using the normal if statement:

main_scene.scene("step1", (scene) => {
	scene.on("message:text", async (ctx) => {
		if (ctx.message.text === "secret") {
			await ctx.reply(`Greetings, mylord`)
			ctx.scenes.move("step3")
		} else {
			await ctx.reply(`Hello`)
			ctx.scenes.move("step2")
		}
	})
})

How to repeat several steps?

You just don’t move off the current step:

const main_scene = new Scene()

main_scene.scene<
	MainBotContext &
		SessionFlavor<{
			main_step1?: {
				names: string[]
			}
		}>
>("step1", (scene) => {
	scene.enter(async (ctx) => {
		await ctx.reply(`Send me 3 names.`)
	})
	scene.on("message:text", async (ctx) => {
		if (!ctx.session.main_step1) {
			ctx.session.main_step1 = { names: [] }
		}
		ctx.session.main_step1.names.push(ctx.message.text)
		if (ctx.session.main_step1.names.length >= 3) {
			await ctx.scenes.move("step2")
		}
	})
})

How would something like using the captcha look?

const captcha_scene = new Scene<
	Context &
		SessionFlavor<{
			captcha?: {
				answer: string
				next_scene: string
			}
		}>
>()
captcha_scene.enter(async (ctx, next_scene) => {
	const { answer, image } = await generateCaptcha()
	ctx.session.captcha = { answer, next_scene }
	await ctx.replyWithPhoto(image)
	await ctx.reply(`Enter letter you see on image above`)
})
captcha_scene.on("message:text", async (ctx) => {
	if (ctx.message.text === ctx.session.captcha?.answer) {
		await ctx.scenes.move(ctx.session.captcha.next_scene)
	} else {
		await ctx.reply(`Please try again.`)
	}
})

const rocket_scene = new Scene()
rocket_scene.enter((ctx) => ctx.scenes.inner("captcha", "launch"))
rocket_scene.scene("captcha", captcha_scene)
rocket_scene.scene("launch", (scene) => {
	scene.enter(async (ctx) => {
		await ctx.reply(`Launching rocket!`)
	})
})

This indeed requires passing the ID of the next (sub)step, but is that really a big deal? The code is still concise and reusable.

If I read move('foo'), I have no idea where to keep on reading.

Most of the time you read the next (sub)scene block. Since that is a 95% use case, this could indeed be improved, with ctx.scene.next() or something along the lines. Respectfully, I agree that naming a scene (a conversation step) should not be necessary. Names should be optional for jumps and such.

1. How does one actually enter (start) a conversation? Please come up with sample top-level bot instance integration.

The only way I see is that one always uses a single top-level conversation with bot.use(topLevelConversation) which in turns handles /commands. Is that what you have in mind?

1. How do you see this:

mainConversation.command('launch_rocket', captcha, async ctx => {
  await ctx.reply('You are verified, launching rocket 🚀')
})

surviving server restart? What if a user takes a 10 minutes break before selecting a month in the captcha sub-conversation, and CI/CD restarts the server during that time?

The command handler is by its nature momentary, it either completes or fails… unless I’m missing something.

1. This proposed API is not exactly obvious:

// First statement
conversation.on('message', ctx => { /* ... */ })
conversation.wait() // <--- what do we "wait" for here? a message (above), or text/photo (below)?
// Second statement
conversation.on('message:text', ctx => { /* ... */ })
conversation.on('message:photo', ctx => { /* ... */ })
conversation.on('message', ctx => { /* ... */ })
conversation.wait()
// Third statement
conversation.on('message', ctx => { /* ... */ })
// <--- why don't we have wait here?

I’d rather suggest something like:

conversation.step(step => {
  step.on('message', ctx => { /* ... */ })
})
conversation.step(step => {
  step.on('message:text', ctx => { /* ... */ })
  step.on('message:photo', ctx => { /* ... */ })
  step.on('message', ctx => { /* ... */ })
})
conversation.step(step => {
  step.on('message', ctx => { /* ... */ })
})

This is immediately obvious what are the conversation steps and how the handlers are grouped. There is also no discrepancy in the number of wait calls. (Essentially, that is what I did in grammy-scenes).

How Approach C Resembles Imperative Code

It struck me that we are getting full flexibility with statements, branching, loops, functions, and recursion using Approach C. In other words, we have the flexibility of code when designing how conversations work. This is a little bit revolutionary and maybe not too obvious on first sight. I would like to illustrate how it will work.

Statements

A statement in conversations is simply all middleware between two wait calls. Example:

// First statement
conversation.on('message', ctx => { /* ... */ })
conversation.wait()
// Second statement
conversation.on('message:text', ctx => { /* ... */ })
conversation.on('message:photo', ctx => { /* ... */ })
conversation.on('message', ctx => { /* ... */ })
conversation.wait()
// Third statement
conversation.on('message', ctx => { /* ... */ })

These individual blocks of handlers act like the individual instructions of a conversation.

Branching

This has already been described in the post above.

In short, you can use filter calls in the middleware (or branch or on or custom middleware or whatever) to perform branching the middleware tree. The branches of the middleware tree translate to the branches of the conversation hierarchy.

Loops

Iteration is possible by recursion (preferred, see below), or by jumping back to a fixed step. Admittedly, this is rather a jump statement than an actual loop. (If you have a use case for for/while/do-while loop and a syntax suggestion, we may add syntactic sugar abstracts away from the jumps.)

Example of jumping back:

conversation.on('message', ctx => { /* ... */ })
conversation.wait('begin-loop') // loop starts here
conversation.on('message', ctx => { /* ... */ }) // first loop statement
conversation.wait()
conversation.on('message', ctx => { /* ... */ }) // second loop statement
conversation.wait()
conversation.filter(condition, ctx => ctx.conversation.resume('begin-loop')) // loop condition
conversation.on('message', ctx => { /* ... */ }) // broke out of loop

Functions

You can define reusable parts of conversations. This lets you define sub-conversations. They can be included in different places of the main conversation, and nested as deep as you like. This is the same concept as functions in code: reusable named pieces of control flow.

In order to illustrate this, lets define a small part of the conversation that verifies the identity of the user by asking for their birthday.

const captcha = new Conversation('captcha', { autoResume: true })
captcha.use(async ctx => {
  await ctx.reply('Please enter your birthday to proceed. Day of month?', {
    reply_markup: numberKeyboard(1, 31) // builds a keyboard 31 buttons with numbers, omitted here
  })
})
captcha.wait()
captcha.on('callback_query:data', async ctx => {
  ctx.session.captcha.day = ctx.callbackQuery.data
  await ctx.reply('Month?', { reply_markup: numberKeyboard(1, 12) })
})
captcha.wait()
captcha.on('callback_query:data', async ctx => {
  ctx.session.captcha.month = ctx.callbackQuery.data
  await ctx.reply('Year?', { reply_markup: numberKeyboard(1900, new Date().getFullYear()) })
})
captcha.wait()
captcha.on('callback_query:data', async ctx => {
  ctx.session.captcha.year = ctx.callbackQuery.data
  await verifyBirthday(ctx, ctx.captcha) // checks birthday against a database, calls `ctx.conversation.leave` if incorrect
})

We now have defined a “function” for checking the birthday. We can “call” the function by passing it as conversational middleware to another conversation.

const mainConversation = new Conversation('rocket-launcher')

mainConversation.command('launch_rocket', captcha, async ctx => {
  await ctx.reply('You are verified, launching rocket 🚀')
})
mainConversation.command('purge', captcha, async ctx => {
  await ctx.reply('You are verified, purging all data')
})

Note how we can use the same captcha in different places. It behaves just like a middleware tree does, and it is closely integrated with grammY’s middleware tree.

Recursion

It should be possible to use the middleware recursively. This implies some sort of call stack, but it isn’t quite clear yet if we actually need to store it or not.

In order to use recursion, we could for example restart the captcha with another attempt if the verification fails. In the last step, we could do:

captcha.on('callback_query:data', async (ctx, next) => {
  ctx.session.captcha.year = ctx.callbackQuery.data
  await next()
})
// `verify` checks the birthday in `ctx.session.captcha` against a database, and returns `true` if it is correct
captcha.filter(verifyBirthday, ctx => ctx.conversation.resume()
// else: restart captcha
captcha.use(async (ctx, next) => {
  await ctx.reply('Wrong birthday, try again!')
  await next()
})
captcha.use(captcha)

This will re-enter the captcha until it is correct.

In reality, you probably also want to allow the user to exit the captcha manually, this was omitted here for brevity.