Scenes (wizards)
The FSM gives you the machinery for a multi-step dialogue: a
conversation is in a state, the state narrows which handler fires, and you
set the next state by hand. That’s transparent — and verbose. A long flow
becomes a wall of stateGroup members, one @OnMessage(State) per step, and an
explicit fsm.set(...) at the end of every handler.
A scene is that same machine with structure on top. You declare an ordered
list of steps; the scene stage numbers them and routes each update to the
current one; you move with next, back or goto instead of naming a state.
It compiles down to the FSM core — no new engine, no parallel pipeline — and
adds four things the bare FSM makes you build yourself:
- Ordered steps. Declaration order is the order;
scene.next()advances by one. No state names, no hand-wired transitions. - Lifecycle prompts.
@OnEntershows the first question;@OnLeaveruns cleanup. Neither is triggered by an update. - Ephemeral data. Each scene has its own scratch object, wiped on
leave— distinct from the long-lived session. - A stack.
enterpushes a sub-dialog;leavepops back to the caller, right where it paused.
If you’ve used aiogram’s scenes (or telegraf’s WizardScene), this is the same
shape in Nest’s vocabulary: a scene is a router, a step is a handler,
the step’s gate is a @Match predicate — the same one FsmState uses.
Turn it on
Import ScenesModule once, alongside NestgramModule, and list your scene
classes in providers like any router:
import { Module } from '@nestjs/common';
import { NestgramModule, ScenesModule } from 'nestgram';
import { RegistrationScene } from './registration.scene';
@Module({
imports: [
NestgramModule.forRoot({
token: process.env.BOT_TOKEN ?? '',
polling: true,
}),
ScenesModule.forRoot(),
],
providers: [RegistrationScene],
})
export class AppModule {}With no options it keeps scene state in process memory — fine for development
and single-instance bots; Setup covers Redis and the
store it shares with sessions and the FSM. If you don’t import ScenesModule,
scenes are off: step predicates never match, and scene.enter(...) throws
rather than silently dropping.
A registration wizard
Three questions — name, age, email — entered from a normal router. The scene is
just a class; each @Step() is a method, gated to “this scene is active AND
this is its current step”:
import {
Scene,
Step,
OnEnter,
OnLeave,
SceneCtx,
SceneContext,
OnText,
OnEmail,
Message,
} from 'nestgram';
export interface RegData {
name: string;
age: string;
email: string;
}
@Scene('registration')
export class RegistrationScene {
@OnEnter()
start() {
return 'What is your name?';
}
@Step()
@OnText()
async name(message: Message, @SceneCtx() scene: SceneContext<RegData>) {
await scene.update({ name: message.text });
return scene.next('How old are you?');
}
@Step({ invalid: 'Please send your age as text.' })
@OnText()
async age(message: Message, @SceneCtx() scene: SceneContext<RegData>) {
await scene.update({ age: message.text });
return scene.next('And your email?');
}
@Step({ invalid: "That doesn't look like an email — try again." })
@OnEmail()
async email(message: Message, @SceneCtx() scene: SceneContext<RegData>) {
await scene.update({ email: message.text });
const { name, age } = scene.data();
return scene.leave(`Done, ${name} (${age})!`);
}
@OnLeave()
async cleanup() {
// side effects only — persist the result, clear a keyboard, …
}
}@OnEnter runs on entry, not on an update — its returned string is the first prompt. @OnLeave runs as the scene ends; its return value is ignored (the closing reply is the argument to scene.leave(...)).
@Step() methods are numbered by declaration order — name is step 0, age step 1, email step 2. No state names anywhere.
@SceneCtx() injects the SceneContext. Type the collected data via the annotation — SceneContext<RegData> — since a decorator argument can’t set the parameter’s type.
scene.update({ … }) merges an answer into the scene’s data; scene.next('…') advances one step and replies the prompt. scene.data() is Partial<RegData>, because a scene fills its fields step by step.
scene.leave('…') ends the scene: @OnLeave runs, the data is wiped, the closing reply is sent.
Enter it from any normal router by handing scene.enter the scene class —
the same @SceneCtx() works there too. enter resolves to the scene’s
@OnEnter reply, so returning it shows the first prompt:
import { Router, Command, Message, SceneCtx, SceneContext } from 'nestgram';
import { RegistrationScene } from './registration.scene';
@Router()
export class EntryRouter {
@Command('register')
register(message: Message, @SceneCtx() scene: SceneContext) {
return scene.enter(RegistrationScene); // shows 'What is your name?'
}
}That’s the whole loop: /register enters, each text reply advances a step, the
last step leaves. Notice what’s not there — no if deciding which question
this is, no state strings, no manual set. The step you’re on decides which
method runs.
When a scene, when raw FSM
A scene is a thin layer over the FSM, so the choice is about shape, not power.
| Reach for a scene | Reach for the raw FSM | |
|---|---|---|
| Shape of the flow | A linear questionnaire — ask, ask, ask, finish. | A branching graph — state A can jump to C, D or back to A. |
| How you move | next/back/goto over ordered steps. | fsm.set(SomeState) by name, transitions you wire. |
| Sub-dialogs | Built in — enter pushes, leave pops. | You model the return path yourself. |
| Cleanup on finish | @OnLeave + automatic data wipe. | fsm.clear() where you decide. |
| The mental cost you pay | Steps are positional — inserting one renumbers. | Every state is named and explicit; nothing is implicit. |
Rule of thumb: a wizard with a clear front-to-back order is a scene; a state machine where transitions fan out by name is the FSM. You can always drop to the FSM under a scene — they share the same store and conversation key.
Steps and lifecycle
A @Step() composes with the @On* filter family:
@Step() @OnText() is a step that fires only on a text message while the scene
sits on it, @Step() @OnPhoto() only on a photo, @Step() @OnCallbackQuery()
(or @Action(...)) on a button tap. The filter is the step’s input contract;
the scene+ordinal gate ANDs onto it. Put @Step() above its filter.
When the filter rejects an update — the user sent a photo where the step
wanted text — the default is to do nothing: the user stays on the step and can
try again. Pass invalid to reply a reprompt instead, gated to the same step
but kind-aware, so a text step reprompts on a non-text message and a callback
step reprompts on a non-matching tap:
@Scene('registration')
export class RegistrationScene {
@Step({ invalid: 'Please send your age as text.' })
@OnText()
async age(message: Message, @SceneCtx() scene: SceneContext<RegData>) {
await scene.update({ age: message.text });
return scene.next('And your email?');
}
}The SceneContext API
@SceneCtx() injects a SceneContext<TData> — the one and only way to drive a
scene. Navigation and data writes are write-through: they persist the moment
their await resolves — the same bargain as FsmContext, so a move survives a
later send failure in the same handler. The navigation methods resolve to their
reply argument, so a handler ends with return scene.next('…') and the
return-value contract replies it.
| Method | Returns | What it does |
|---|---|---|
current() | { scene, step }/null | The active scene id + step ordinal, or null when no scene is running. |
data() | Partial<TData> | The data gathered so far — partial, since a scene fills it step by step. |
update(patch) | Promise<void> | Merge a patch into the active scene’s data. |
setData(data) | Promise<void> | Replace the active scene’s data wholesale. |
next(reply?) | Promise<string|void> | Advance one step (clamped to the last); resolves to reply. |
back(reply?) | Promise<string|void> | Go back one step (never before the first); resolves to reply. |
goto(step, reply?) | Promise<string|void> | Jump to a step by ordinal or step-method name; resolves to reply. |
enter(scene, data?) | Promise<string|void> | Enter a (sub-)scene — push the current one, run the new scene’s @OnEnter, resolve to its prompt. |
leave(reply?) | Promise<string|void> | Leave the active scene — run @OnLeave, wipe its data, pop a parent if one is stacked; resolves to reply. |
A few precise notes:
gototakes a name or an ordinal.scene.goto('email')jumps to the step method namedemail;scene.goto(2)to ordinal 2. An out-of-range ordinal throws — it isn’t silently clamped, because a typo’d jump is a bug, not a no-op.next/backare clamped:backon the first step stays put,nexton the last step stays put.enterseeds data.scene.enter(SubScene, { from: 'menu' })starts the sub-scene with that ephemeral data already in place.- The data is yours.
TDatais whatever the scene collects; the framework reserves no fields. Type it via the@SceneCtx() scene: SceneContext<RegData>annotation and keep the interface beside the scene.
The scene stack
enter doesn’t only start a scene from idle — called from inside a scene it
pushes the current one onto a stack and runs the new one as a sub-dialog. When
that sub-dialog calls leave, the parent pops back into place, resumed at
the step after the one that spawned it. Ask a question mid-flow without losing
your place:
import {
Scene,
Step,
OnEnter,
SceneCtx,
SceneContext,
OnText,
Message,
} from 'nestgram';
import { AddressScene } from './address.scene';
@Scene('order')
export class OrderScene {
@OnEnter()
start() {
return 'What are you ordering?';
}
@Step()
@OnText()
async item(message: Message, @SceneCtx() scene: SceneContext) {
await scene.update({ item: message.text });
return scene.enter(AddressScene); // push: ask for the address
}
@Step()
@OnText()
async confirm(message: Message, @SceneCtx() scene: SceneContext) {
// Runs only after AddressScene popped back and advanced this scene.
return scene.leave('Order placed!');
}
}The sub-dialog’s own data is independent and wiped when it leaves — only the parent’s data survives the pop. That’s the heart of the three-tier model: a scene’s data is the shortest-lived state in the bot.
| State | Scope | Lifetime |
|---|---|---|
| Session | per conversation | Persists indefinitely (until you delete it). |
| FSM data | per conversation | Lives while a flow runs; dropped on fsm.clear(). |
| Scene data | per active scene on the stack | Lives while that scene is active; wiped on leave. |
A session is a user’s long-lived memory (their cart, their settings); scene data is the scratch pad for the dialogue happening right now. Finishing a wizard shouldn’t wipe a user’s preferences — keep the durable bits in the session and read them from the scene as needed.
Setup and the gates
ScenesModule.forRoot({ store }) takes the same KeyValueStore as
sessions and the FSM — three methods
(get/set/delete). The default is an in-process MemoryStore; point it at
a Redis-backed store to persist and share across instances. Scene records are
namespaced inside the store, so handing all three facilities one store
instance is safe — they never collide:
import { ScenesModule, RedisSessionStore } from 'nestgram';
import Redis from 'ioredis';
ScenesModule.forRoot({
store: new RedisSessionStore(new Redis(), { prefix: 'nestgram:' }),
});The conversation key is the same defaultConversationKey sessions and the FSM
use — per chat + user (plus forum topic and business connection), so in a
group every member walks their own wizard. Override key to rescope, or return
undefined to skip scenes for an update:
ScenesModule.forRoot({
// one wizard per chat — everyone in a group advances the same flow
key: (ctx) => (ctx.chat ? `chat:${ctx.chat.id}` : undefined),
});Capturing input: an active scene and @InScene()
While a scene is running it captures input. Only the scene’s own @Step()
handlers are eligible to match — every other handler is suppressed for the
duration of the scene. That’s the behavior you want by default: a catch-all
@OnMessage(), a stray @Command, an unrelated button handler can’t steal a
step’s input or fire mid-wizard. When no scene is active, routing is normal —
all handlers match, and the steps simply don’t.
So a catch-all needs no guard to stay out of a wizard’s way:
import {
Router,
Command,
OnMessage,
Message,
SceneCtx,
SceneContext,
} from 'nestgram';
import { RegistrationScene } from './registration.scene';
@Router()
export class EntryRouter {
@Command('register')
register(message: Message, @SceneCtx() scene: SceneContext) {
return scene.enter(RegistrationScene);
}
// No guard needed: while a scene runs this is suppressed automatically.
@OnMessage()
echo(message: Message) {
return message.text;
}
}To run a handler mid-scene — a global /cancel that bails out of any
wizard, say — opt it in with @InScene(). It marks the handler as exempt from
the capture, so it fires both while idle and while a scene is active (its own
@Command/@OnMessage/… filters still apply):
import {
Router,
Command,
InScene,
Message,
SceneCtx,
SceneContext,
} from 'nestgram';
@Router()
export class EntryRouter {
// Exempt from capture: fires mid-scene (and idle). Order doesn't matter —
// capture is decided by the scene gate, not first-match position.
@Command('cancel')
@InScene()
cancel(message: Message, @SceneCtx() scene: SceneContext) {
return scene.leave('Cancelled.');
}
}An active scene captures all input, not just text — an unrelated inline
button callback is suppressed mid-scene too, unless its handler is marked
@InScene(). If a button outside the wizard must keep working while a scene runs
(a persistent menu, a cancel button), add @InScene() to its handler.
@InScene() is determinism-friendly: because capture is decided by the
SceneRouteGate (a @RouteTransform that ANDs an idle predicate onto every
non-step, non-exempt route at boot), not by declaration order, a step always
wins over a would-be catch-all regardless of which router declares what first.
@InScene() is a one-liner over the public @Match()
primitive — the same one @Step() uses to AND its scene+ordinal gate. The
marker is a no-op predicate the boot-time scene gate recognises; nothing
privileged, you could rebuild it in three lines.Two fast steps in one chat
A wizard reads the previous answer to decide the next prompt, so overlapping
updates would race on the scene record. They don’t. The on-by-default in-process
update queue (QueuedUpdateSource) serialises each chat’s updates per-chat
FIFO before dispatch — under both polling and webhook, since it wraps
whichever source the transport seam produced. Two messages fired off in quick
succession run one at a time in arrival order; different chats still run in
parallel.
So within a single instance, two fast steps in one conversation cannot interleave: the second update waits for the first’s dispatch to start before it is admitted, and the first has already written its transition through (writes are write-through) by then.