@gramio/dialogs

Declarative, stateful dialogs and reusable widgets for GramIO — you describe a screen as a tree of widgets, and the engine handles message send/edit/delete, callback_data routing, and stack-based navigation. Inspired by aiogram_dialog, reimagined for TypeScript.

Warning

Work in progress. This library is under active development and the public API may change between releases without notice. Pin an exact version and review the changelog before upgrading.

Install

npm install @gramio/dialogs
# bun add @gramio/dialogs · pnpm add @gramio/dialogs · yarn add @gramio/dialogs

gramio is a peer dependency. Works on Node ≥ 20, Bun, and Deno; ships ESM, CJS, and .d.ts. Persistence plugs into any @gramio/storage adapter (in-memory, Redis, Cloudflare KV, …).

Mental model in 30 seconds

Dialog ("menu")  ── a state group: one set of related screens + lifecycle
 ├─ Window "main"      ── one screen for one state key
 │    ├─ getter        ── load data for this render
 │    ├─ text/media    ── what to show
 │    └─ keyboard      ── a widget tree (buttons, layout, stateful, …)
 └─ Window "settings"
        └─ …

         ▲ rendered to ONE Telegram message, edited in place on every action

Dialog — a group of windows that share state, data, and lifecycle hooks (onStart / onClose / access). One dialog id = one "screen flow".
Window — a single screen bound to a state key. It owns the text, media, and keyboard widget tree, plus an optional getter and input handler.
ctx.dialog — the navigation surface on every update: start / switchTo / back / next / done, plus the data buckets (params / dialogData).

You never call editMessageText, build callback_data, or write an FSM. You mutate state and the active window re-renders itself into the same message.

5-minute example

import { Bot } from "gramio";
import {
  Dialog, dialogs, Group, Column, SwitchTo, Back, Button, Counter,
} from "@gramio/dialogs";

const menu = new Dialog("menu")
  .window("main", {
    getter: (ctx) => ({ name: ctx.from?.firstName ?? "there" }),
    text: (d) => `Hello, ${d.name}! Choose an option:`,
    keyboard: Group([
      SwitchTo("⚙️ Settings", "settings"),
      Button("🔔 Ping", { id: "ping", onClick: (ctx) => ctx.answer("pong") }),
    ], { width: 1 }),
  })
  .window("settings", {
    text: "⚙️ Settings",
    keyboard: Column([
      Counter({ id: "volume", default: 5, min: 0, max: 10, text: (d) => `🔊 ${d.value}` }),
      Back("◀ Back"),
    ]),
  });

new Bot(process.env.BOT_TOKEN!)
  .extend(dialogs([menu]))
  .command("start", (ctx) => ctx.dialog.start("menu"))
  .start();

What you didn't write: no editMessageText, no callback_data strings, no bot.callbackQuery(...) routing, no per-user FSM, no manual "which message do I edit?" bookkeeping. SwitchTo, Counter, and Back carry their own behaviour.

What happens when an update arrives

message | callback_query
        │
        ▼
  derive ctx.dialog (load stack from storage, key: grd:<senderId>)
        │
   ┌────┴───────────────┐
callback_query        message
   │                     │
unpack callback_data   reply-keyboard payload? ─yes─► route as a callback
   │                     │ no
ours? ─no─► next()     window.input → onMessage
   │ yes                 │
intent == active        handled ─► persist
dialog instance?        else ────► next()  (not ours → other handlers run)
   │   └─no─► onStale (silent answer by default)
access ok? ─no─► onAccessDenied
   │ yes
widget onClick mutates state
   │
re-render (Edit) ─► persist stack

The plugin owns only what it recognises: a tap whose callback_data doesn't match the active dialog instance falls straight through to next(), so dialogs coexist with your normal command / on handlers.

What goes where — the decision guide

You want to…	Put it on…	Why
Load data for a screen	`getter` (window, or dialog-level)	runs before each render; its output is the `data` your `text`/`keyboard` see
Decide what to show	`text` / `media` / `keyboard` on the window	declarative; re-rendered after every action
Pass a one-off arg into a run	`start(id, state, { data })` → `ctx.params`	immutable for the life of that dialog instance
Keep mutable state across screens	`ctx.dialogData`	survives `switchTo` / `next` within the dialog
Store a widget's own value	give the widget an `id` → `ctx.widgetData(id)` / typed accessors	persisted per widget, per dialog instance
React to a tap	`onClick` on a `Button`	receives the nav surface (`ctx.switchTo`, …)
Consume free text	`input` (e.g. `TextInput`) or `onMessage`	`input` runs first; falls through if it doesn't handle it
Hand a result back to the opener	`ctx.done(result)`	the parent dialog's `onProcessResult` receives it
Guard who may interact	`access` / `onAccessDenied`	runs on every update routed into the dialog
Edit a dialog from outside a handler	`createDialogs(...).background(...)`	headless render that edits the last message

The three data buckets

A dialog instance carries three independent stores. Keep them straight and most "where does this value live?" questions disappear.

const confirm = new Dialog<{ orderId: number }>("confirm").window("ask", {
  // params: the immutable data passed to start() — typed by Dialog<Params>
  getter: (ctx) => ({ orderId: ctx.params.orderId, attempts: ctx.dialogData.tries ?? 0 }),
  text: (d) => `Confirm order #${d.orderId}? (tries: ${d.attempts})`,
  keyboard: Column([
    Button("Retry", { id: "retry", onClick: (ctx) => {
      ctx.dialogData.tries = (ctx.dialogData.tries ?? 0) + 1; // mutable, survives re-render
      return ctx.show();
    }}),
    Button("Yes", { id: "y", onClick: (ctx) => ctx.done(true) }), // result → opener
  ]),
});

Bucket	Set by	Read as	Lifetime
start params	`start(id, state, { data })`	`ctx.params` (readonly)	the dialog instance
dialog data	`ctx.dialogData.x = …` or `ctx.dialog.update({ … })`	`ctx.dialogData`	the dialog instance
widget data	widget interaction, or `ctx.widgetData(id, fallback)`	typed accessors (below)	the dialog instance
getter output	a `getter` function	the `data` arg in `text`/`keyboard`	recomputed every render

Inside a render, data is dialog.getter ⊕ window.getter output, plus data.dialogData and data.startData for convenience. The order matters: getters run first, so a getter reads the live dialog data via ctx.dialogData (also ctx.params) — not via its own data arg, which doesn't exist yet. In text / keyboard, read rc.data.dialogData.

Navigation — `ctx.dialog` (and flat `ctx.*`)

Every method on the manager is also mirrored flat on the context, so ctx.switchTo("settings") ≡ ctx.dialog.switchTo("settings").

ctx.dialog                                   // the DialogManager itself
ctx.start(dialog, state?, { data?, mode?, startMode? })  // open a dialog (push)
ctx.switchTo(state, mode? | { data?, mode? })  // jump to a window; `{ data }` merges into dialogData FIRST
ctx.back(mode?)              // history: undo the last switchTo / next
ctx.next(mode?)              // next window in declaration order (linear wizards)
ctx.done(result?, mode?)     // close this dialog, hand result to the opener
ctx.show(mode?)              // re-render current window, no state change
ctx.widgetData(id, fallback) // read/seed a widget's stored value
ctx.dialogData               // mutable per-dialog bag (getter/setter)
ctx.params                   // immutable start params

// only on ctx.dialog (not mirrored flat):
ctx.dialog.update(partial, mode?)        // merge into dialogData + re-render
ctx.dialog.setData(partial)              // merge into dialogData + persist, NO render
ctx.dialog.counter(id)                   // { get, set }
ctx.dialog.checkbox(id)                  // { checked, set, toggle }
ctx.dialog.radio(id)                     // { selected, set }
ctx.dialog.multiselect(id)               // { selected, isSelected, set, toggle }
ctx.dialog.history                       // string[] of visited states

back is history-based (where you came from), next is order-based (the next .window(...) declared). next also records history, so a paired Back() undoes it.
ShowMode controls delivery: Auto (edit on callback, send on message) · Send · Edit · Delete (delete + resend — needed for media↔text switches).
A no-op edit (clicking a button that re-renders the same screen) is swallowed — Telegram's message is not modified is expected, not an error.

Stack navigation & nested dialogs

Dialogs form a stack per (chat, user). start pushes, done pops and returns a result to the dialog underneath.

const parent = new Dialog("parent", {
  // receives the child's result when it closes:
  onProcessResult: (ctx, childStartData, result) => ctx.dialog.update({ picked: result }),
}).window("main", {
  text: (d) => `Picked: ${d.dialogData.picked ?? "—"}`,
  keyboard: Column([Start("Pick a date", "datepicker")]), // push child dialog
});

const datepicker = new Dialog("datepicker").window("pick", {
  text: "Pick one",
  keyboard: Column([Button("Today", { id: "t", onClick: (ctx) => ctx.done("2026-06-19") })]),
});

StartMode controls how start treats the existing stack:

Mode	Effect
`StartMode.Normal` (default)	push on top of the current stack
`StartMode.ResetStack`	clear the current stack first — the new dialog stands alone
`StartMode.NewStack`	open an independent parallel stack; the old one stays alive

Closing the last dialog on a stack deletes its message (and dismisses any reply keyboard). Parallel stacks route by intent id, so two independent flows can live in one chat at once. (Stack depth is capped at 100 as an abuse guard.)

Typed dialogs — `defineDialog`

For typed states and typed dialogData / params, use the builder. State typos become compile errors (including forward references), and getter/handler contexts are fully typed.

import { defineDialog, Column } from "@gramio/dialogs";

const wb = defineDialog("wizard")
  .states("name", "confirm")     // the state union — switchTo only accepts these
  .params<{ chatId: number }>()  // ctx.params type
  .data<{ score: number }>();    // ctx.dialogData type

wb.window("name", {
  getter: (ctx) => ({ hi: ctx.from?.firstName ?? "?" }), // ctx.params: { chatId }
  text: (d) => `Hi ${d.hi}`,
  keyboard: Column([wb.switchTo("Next ▶", "confirm")]),   // "confirm" ✓, "typo" ✗
});
wb.window("confirm", { text: "Done", keyboard: Column([wb.cancel("Close")]) });

const wizard = wb.build(); // → a Dialog; register via dialogs([wizard])

The builder exposes typed switchTo / next / back / cancel / start / button helpers, plus wb.nav(ctx) to narrow a raw handler context to the dialog's states. Passing a built TypedDialog to Start(...) / ctx.start(...) type-checks the target's state and data. See examples/typed.ts.

Input, media & reply keyboards

// free-text input — `input` is consulted before `onMessage`
new Dialog("ask").window("name", {
  text: "What's your name?",
  input: TextInput({ id: "name", onSuccess: (ctx, value) => ctx.done(value) }),
});

// media — text↔media transitions are handled automatically (delete + resend)
.window("photo", { media: StaticMedia(fileId, "photo"), text: "caption" })

// reply keyboard — callbacks smuggled in invisible chars, so widgets still work
.window("menu", { reply: true, keyboard: Column([Button("Tap", { id: "x", onClick })]) })

Reply-keyboard windows always send a fresh message (reply keyboards can't be edited in place), and RequestUser / RequestChat / ContactRequest / LocationButton only render inside reply: true windows.

Background updates (edit from outside a handler)

createDialogs returns the plugin plus a background factory — render into a user's dialog message from a timer, webhook, or queue worker.

const { plugin, background } = createDialogs([menu]);
bot.extend(plugin);

// later, with no incoming update:
const mgr = await background(bot, `grd:${userId}`); // stack key
await mgr.update({ price: 42 });                    // edits the last rendered message

It defaults to editing the last message and throws if the stack has never been rendered (there's no message to edit).

Stage data, then navigate. From a background callback the user may have left the window you expect, so re-rendering the current one (update) can be wrong. Set the data without rendering, then jump to the target — only the target window renders:

await mgr.setData({ failReason });        // merge into dialogData, no render
await mgr.switchTo("login_fail");         // renders the TARGET window
// …or in one call:
await mgr.switchTo("login_fail", { data: { failReason } });

Headless getters must be render-source agnostic. Under background() the context is synthetic: ctx.is(...) is always false, and ctx.from / ctx.chatId / ctx.senderId all resolve to the chat id (private chats only). Read the user id as ctx.from?.id and don't reach for interactive-only update fields — a getter that does will work live but render undefined from the background.

Plugin registration & options

bot.extend(dialogs([menu, wizard], {
  storage: redisStorage(),                 // default: in-memory (dev only)
  getStackKey: (ctx) => `grd:${ctx.chatId}:${ctx.senderId}`, // default: grd:<senderId>
  i18n: (ctx) => ctx.t,                    // translator for the T() widget
  callback: { name: "myprefix" },          // rename the "grd" callback_data scheme
  events: {                                // overridable engine answers (silent by default)
    onStale: (ctx) => ctx.answer("This menu has expired"),
    onAccessDenied: (ctx) => ctx.answer("Not for you"),
  },
}));

Option	Type	Default	Description
`storage`	`@gramio/storage` adapter	in-memory	where dialog stacks are persisted
`getStackKey`	`(ctx) => string`	`grd:<senderId>`	partitions stacks (per-chat, per-thread, …)
`i18n`	`(ctx) => Translator`	`ctx.t` if present, else echo	resolves the `T(key)` text widget
`callback`	`{ name }` or `{ pack, unpack }`	built-in `"grd"` codec	customise `callback_data` encoding
`events`	`{ onStale?, onAccessDenied? }`	silent answer	global hooks for engine-generated answers

dialogs(list, opts) is sugar over createDialogs(list, opts).plugin.

Widgets

Every text slot accepts a bare string, a (data) => … function, or a text widget — no Const / Format wrapper needed. Buttons have positional overloads and an options form:

SwitchTo("⚙️ Settings", "settings");                                  // positional
SwitchTo({ text: "⚙️ Settings", state: "settings", icon, style });    // options
SwitchTo("Settings", "settings", { icon: "5283103725936750105", style: "primary" }); // custom emoji

Group	Widgets
Text	`Const`, `Format`, `Multi`, `Case`, `List`, `Progress`, `T` (i18n) · helper `asText`
Actions	`Button`, `SwitchTo`, `Back`, `Next`, `Cancel`, `Start`, `Url`, `WebApp`, `SwitchInlineQuery`
Layout	`Group(children, { width })`, `Row`, `Column`
Stateful	`Counter`, `Select`, `Multiselect`, `Radio`, `Checkbox`, `Toggle` · helpers `getSelected`, `getToggle`, `isChecked`
Forms	`Rating`, `Slider`, `Confirm`, `Stepper`, `PinPad`, `TagInput`, `Form` (Standard Schema) · helpers `getRating`, `getSlider`, `getPin`, `getTags`, `addTag`, `getFormValues`
Data	`Tabs`, `Accordion`, `Breadcrumbs`, `Grid`, `AsyncSelect` · helper `getTab`
Complex	`Calendar` (+ `marks`), `ScrollingGroup` + `First/Prev/Next/LastPage`/`CurrentPage` (+ `pageState`), `ListGroup` (+ `listItemId`)
Native	`Poll`, `Reactions`, `RequestUser`, `RequestChat`, `ContactRequest`, `LocationButton` · helpers `getReactions`, `getSharedUsers`, `getSharedChat`
Live	`Spinner`, `Countdown`, `LiveProgress`, `typing` / `withTyping`
Money / AI	`StarsButton` (Telegram Stars), `stream` (`sendMessageDraft`)
Charts / codes	`Sparkline`, `BarChart`, `Gauge`, `QR`, `Barcode`
Input / Media	`TextInput` (+ `getInput`), `StaticMedia`, `DynamicMedia`, `MediaScroll` (+ `mediaScrollPage`)

Stateless Select over external state. For a Select backed by a source of truth you own (a setting in your DB, not widget data), pass selected to mark the current choice — the matching item gets a ✓ (override via selectedMark) and checked: true in its text state, so you don't compute the mark by hand:

Select({
  id: "lang", items: (d) => d.langs, itemId: (l) => l.code,
  text: (st) => st.item.name,
  selected: (d) => d.currentLang,      // → "English ✓"
  onClick: (ctx, code) => saveLang(ctx.from!.id, code),
});

callback_data budget: Telegram caps inline callback_data at 64 bytes and rejects the whole keyboard if you exceed it. Use short item ids (list indices), never long strings, as widget payloads — the engine warns once per widget in dev if you overflow.

Each widget is shown in use in the examples.

API surface

The low-level building blocks behind the sugar are all exported, if you need them:

Engine: dialogs / createDialogs, DialogManager, DialogRegistry, StackRepository, makeCodec.
Building blocks: Dialog (also new Dialog({ id, windows: [new Window(...)] })), Window, defineWindow, defineDialog / DialogBuilder.
Enums: StartMode (Normal / ResetStack / NewStack), ShowMode (Auto / Send / Edit / Delete).
Types: RenderContext<Data>, Getter, ClickCtx / InputCtx, TextSource / TextWidget, Keyboard, MediaWidget, DialogEvents, AccessCheck, plus the Typed* family — see src/index.ts.

Storage shape (what lands in your @gramio/storage adapter): a StackStore of { stacks: DialogStack[]; currentId }, where each DialogStack holds the intents (dialog instances with stateKey, data, widgetData, history) and the last chatId / messageId. With a single stack it collapses to a plain DialogStack for back-compat.

Examples

Each file in examples/ is a self-contained, runnable bot (see examples/README.md):

File	Showcases
`basic.ts`	minimal two-screen dialog
`api-styles.ts`	the same dialog 5 ways + typed cross-dialog transitions
`widgets.ts`	widget gallery — text, stateful, forms + `Form`, data/selection, calendar, pagination, input
`charts.ts`	visuals — `Sparkline`/`BarChart`/`Gauge` + media (`QR`/`Barcode`/`StaticMedia`/`DynamicMedia`/`MediaScroll`)
`realtime.ts`	live widgets, native `Poll`/`Reactions`/pickers, Stars + AI streaming
`typed.ts`	`defineDialog` typed states + `nav`, access, i18n, `MediaScroll`, calendar marks
`typed-and-nested.ts`	`Dialog<Params>` + nested dialog results
`views-and-dialogs.ts`	coexistence with `@gramio/views`
`scenes-and-dialogs.ts`	incremental adoption with `@gramio/scenes`
`assistant/`	🤖 real-app composition — `node:sqlite` webhook inbox, calendar, AI summary, Stars, live push

Development

bun install
bun run typecheck      # tsc -p tsconfig.build.json (src) — publish gate
bun run typecheck:all  # tsc over src + tests + examples
bun test               # bun:test — fake-bot unit harness + real-bot integration (@gramio/test)
bun run lint           # biome
bun run build          # pkgroll → dist (esm + cjs + d.ts)

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
.github/workflows		.github/workflows
examples		examples
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
biome.json		biome.json
bun.lock		bun.lock
deno.json		deno.json
package.json		package.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

@gramio/dialogs

Install

Mental model in 30 seconds

5-minute example

What happens when an update arrives

What goes where — the decision guide

The three data buckets

Navigation — `ctx.dialog` (and flat `ctx.*`)

Stack navigation & nested dialogs

Typed dialogs — `defineDialog`

Input, media & reply keyboards

Background updates (edit from outside a handler)

Plugin registration & options

Widgets

API surface

Examples

Development

License

About

Uh oh!

Releases 3

Packages

Uh oh!

Contributors

Uh oh!

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

@gramio/dialogs

Install

Mental model in 30 seconds

5-minute example

What happens when an update arrives

What goes where — the decision guide

The three data buckets

Navigation — ctx.dialog (and flat ctx.*)

Stack navigation & nested dialogs

Typed dialogs — defineDialog

Input, media & reply keyboards

Background updates (edit from outside a handler)

Plugin registration & options

Widgets

API surface

Examples

Development

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Navigation — `ctx.dialog` (and flat `ctx.*`)

Typed dialogs — `defineDialog`

Packages