### Quickstart: Bot with Conversations Plugin

Source: https://github.com/grammyjs/conversations/blob/main/README.md

This snippet demonstrates how to install and set up the grammY conversations plugin. It defines a simple greeting conversation and integrates it into a bot. Use this to quickly get started with creating conversational features.

```typescript
import {
    Bot,
    type Context
} from "grammy";
import {
    type Conversation,
    type ConversationFlavor,
    conversations,
    createConversation,
} from "@grammyjs/conversations";

type MyContext = ConversationFlavor<Context>;
type MyConversationContext = Context;

type MyConversation = Conversation<MyContext, MyConversationContext>;

const bot = new Bot<MyContext>("");

/** Defines the conversation */
async function greeting(
    conversation: MyConversation,
    ctx: MyConversationContext,
) {
    await ctx.reply("Hi there! What is your name?");
    const { message } = await conversation.wait();
    await ctx.reply(`Welcome to the chat, ${message.text}!`);
}

bot.use(conversations());
bot.use(createConversation(greeting));

bot.command("enter", async (ctx) => {
    await ctx.reply("Entering conversation!");
    // enter the function "greeting" you declared
    await ctx.conversation.enter("greeting");
});

bot.command("start", (ctx) => ctx.reply("Hi! Send /enter"));
bot.use((ctx) => ctx.reply("What a nice update."));

bot.start();

```

--------------------------------

### Complete Minimal Bot Example with Conversations

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/setup.md

A full, minimal example demonstrating the setup of the grammY conversations plugin, including context type definition, plugin installation, conversation creation, and starting the bot.

```typescript
import { Bot, Context } from "grammy";
import {
    ConversationFlavor,
    Conversation,
    conversations,
    createConversation,
} from "@grammyjs/conversations";

// 1. Define context type
type MyContext = ConversationFlavor<Context>;

// 2. Create bot
const bot = new Bot<MyContext>("");

// 3. Install plugin (with in-memory storage)
bot.use(conversations());

// 4. Define conversation
async function welcome(conversation: Conversation<MyContext>, ctx: MyContext) {
    await ctx.reply("Welcome! What's your name?");
    const { message } = await conversation.wait();
    await ctx.reply(`Nice to meet you, ${message.text}!`);
}

// 5. Register conversation
bot.use(createConversation(welcome));

// 6. Command to start conversation
bot.command("start", async (ctx) => {
    await ctx.conversation.enter("welcome");
});

// 7. Start bot
bot.start();
```

--------------------------------

### Example Key-Based Storage Configuration

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/storage.md

An example of configuring key-based storage with a custom prefix and storage key derivation function.

```typescript
const storage: ConversationKeyStorage<Context, ConversationData> = {
    type: "key",
    version: 1,
    prefix: "convo_",
    getStorageKey: ctx => `chat_${ctx.chatId}`,
    adapter: myFileSystemAdapter,
};
```

--------------------------------

### Enter a Conversation via Command

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/setup.md

Use a command handler to enter a specific conversation. This example shows how to start the 'greeting' conversation when the '/start' command is received.

```typescript
bot.command("start", async (ctx) => {
    await ctx.conversation.enter("greeting");
});

bot.start();
```

--------------------------------

### Example Context-Based Storage Configuration

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/storage.md

An example of context-based storage using a custom adapter that derives keys from chat and user IDs.

```typescript
const storage: ConversationContextStorage<Context, ConversationData> = {
    type: "context",
    version: 1,
    adapter: {
        async read(ctx) {
            const key = `${ctx.chatId}_${ctx.from?.id}`;
            return await db.get(key);
        },
        async write(ctx, state) {
            const key = `${ctx.chatId}_${ctx.from?.id}`;
            await db.set(key, state);
        },
        async delete(ctx) {
            const key = `${ctx.chatId}_${ctx.from?.id}`;
            await db.delete(key);
        },
    },
};
```

--------------------------------

### Complete Setup with Custom File Storage Adapter

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/storage.md

Provides a full example of setting up grammY conversations with a custom file system storage adapter. This includes defining read, write, and delete operations for persisting conversation data to local files.

```typescript
import { Bot, Context } from "grammy";
import { 
    conversations, 
    createConversation, 
    ConversationFlavor,
    ConversationData,
    pinVersion 
} from "@grammyjs/conversations";
import { readFile, writeFile, mkdir, unlink } from "fs/promises";
import { join } from "path";

type MyContext = ConversationFlavor<Context>;

const bot = new Bot<MyContext>("");

const dataDir = "./conversation_data";
const { versionify, unpack } = pinVersion(0);

const fileAdapter = {
    async read(key: string) {
        try {
            const data = await readFile(
                join(dataDir, `${key}.json`),
                "utf-8"
            );
            return JSON.parse(data) as any;
        } catch {
            return undefined;
        }
    },

    async write(key: string, state: any) {
        await mkdir(dataDir, { recursive: true });
        await writeFile(
            join(dataDir, `${key}.json`),
            JSON.stringify(state)
        );
    },

    async delete(key: string) {
        try {
            await unlink(join(dataDir, `${key}.json`));
        } catch {
            // File already deleted
        }
    },
};

bot.use(conversations({
    storage: {
        type: "key",
        version: 0,
        adapter: fileAdapter,
    },
}));

async function myConversation(conversation: any, ctx: MyContext) {
    await ctx.reply("What's your name?");
    const { message } = await conversation.wait();
    await ctx.reply(`Welcome, ${message.text}!
`);
}

bot.use(createConversation(myConversation));

bot.command("start", async (ctx) => {
    await ctx.conversation.enter("myConversation");
});

bot.start();
```

--------------------------------

### ReplayEngine Usage Example

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/engine.md

Demonstrates how to create a new ReplayEngine instance and define its builder function, including interrupts and actions.

```typescript
const engine = new ReplayEngine(async (controls) => {
    const value = await controls.interrupt("first");
    console.log(value);
    
    const result = await controls.action(() => {
        return Math.random();
    }, "random");
    
    console.log(result);
});
```

--------------------------------

### play() Method Example

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/engine.md

Shows how to initiate a new execution using the play() method and handle the ReplayResult, including interrupted states.

```typescript
const result = await engine.play();
if (result.type === "interrupted") {
    const state = result.state;
    const interrupts = result.interrupts;
}
```

--------------------------------

### Complete Interactive Counter Menu Example

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/menus.md

An example demonstrating how to create an interactive counter menu within a conversation. It includes sending the menu, handling button presses, and updating the menu dynamically.

```typescript
async function menuExample(conversation, ctx) {
    // Create root menu
    let count = 0;
    const menu = conversation.menu("counter")
        .text(() => `Count: ${count}`, ctx => {
            count++;
            ctx.menu.update();
        })
        .row()
        .text("Reset", ctx => {
            count = 0;
            ctx.menu.update();
        });

    // Send menu
    await ctx.reply("Interactive counter:", { 
        reply_markup: menu 
    });

    // Keep waiting for interactions
    while (count < 10) {
        await conversation.wait();
    }

    await ctx.reply("Reached 10!");
}
```

--------------------------------

### Install Conversations Plugin

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/setup.md

Install the conversations plugin into your bot instance. This enables conversation functionality.

```typescript
import { conversations } from "@grammyjs/conversations";

bot.use(conversations());
```

--------------------------------

### Data Versioning Example

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/storage.md

Demonstrates how to configure storage with different versions. Old conversations are discarded when the version number changes.

```typescript
const v0Adapter = /* ... */;

// Start: version 0
bot.use(conversations({
    storage: {
        type: "key",
        version: 0,
        adapter: v0Adapter,
    },
}));

// After code change: version 1
bot.use(conversations({
    storage: {
        type: "key",
        version: 1,
        adapter: v0Adapter,
    },
}));
```

--------------------------------

### Install and Use File System Adapter

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/storage.md

Demonstrates how to install and use the file system storage adapter for grammY conversations. Ensure the adapter is imported and then passed to the conversations plugin configuration.

```typescript
import { FileAdapter } from "@grammyjs/storage-file";

bot.use(conversations({
    storage: {
        type: "key",
        adapter: new FileAdapter("./data"),
    },
}));
```

--------------------------------

### open() Static Method Example

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/engine.md

Illustrates creating an initial replay state using open() and then supplying a value to resolve the first interrupt.

```typescript
const [state, interrupt] = ReplayEngine.open("user-input");

// Supply a value for the interrupt
ReplayEngine.supply(state, interrupt, userMessage);

// Replay will now resolve the interrupt with the supplied value
const result = await engine.replay(state);
```

--------------------------------

### Storage Key Formats

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/storage.md

Examples of how to format storage keys, including using chat ID and custom prefixes or functions.

```typescript
// Default: "123456789" for chat ID 123456789
const key = ctx.chatId.toString();

// Custom prefix
const prefixedKey = "convo_" + ctx.chatId.toString();

// Custom function
const key = ctx.from?.id + "_" + ctx.chatId;
```

--------------------------------

### supply() Static Method Example

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/engine.md

Shows how to use supply() to provide values for interrupts during replay, including resetting to a previous checkpoint.

```typescript
const [state, int] = ReplayEngine.open("request");

// First time: supplies "hello" to the interrupt
ReplayEngine.supply(state, int, "hello");
let result1 = await engine.replay(state);

// Reset to before the supply
ReplayEngine.reset(state, checkpoint);

// Second time: supplies "goodbye"
ReplayEngine.supply(state, int, "goodbye");
let result2 = await engine.replay(state);
```

--------------------------------

### replay() Method Example

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/engine.md

Demonstrates resuming execution with replay() after an interruption. It shows how to capture state, supply an interrupt value, and replay.

```typescript
let state = (await engine.play() as Interrupted).state;

// Supply an interrupt value
const checkpoint = ReplayEngine.supply(state, 0, "hello");

// Replay with the new value
const result = await engine.replay(state);
```

--------------------------------

### Install grammY Conversations Plugin

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/setup.md

Install the plugin using npm. Requires grammy version 1.20.1 or later and Node.js 12.20.0 or later.

```bash
npm install @grammyjs/conversations
```

--------------------------------

### Install Conversations Plugin

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/api-reference.md

Installs the conversations plugin middleware on a grammY bot. Can be configured with custom storage and callbacks.

```typescript
import { Bot, Context } from "grammy";
import { conversations, createConversation, ConversationFlavor } from "@grammyjs/conversations";

type MyContext = ConversationFlavor<Context>;

const bot = new Bot<MyContext>("");

// Install with default options (in-memory storage)
bot.use(conversations());

// Or with storage and callbacks
bot.use(conversations({
    storage: {
        type: "key",
        version: 0,
        adapter: customStorageAdapter,
    },
    onEnter: (id, ctx) => console.log(`Entered: ${id}`),
    onExit: (id, ctx) => console.log(`Exited: ${id}`),
}));
```

--------------------------------

### Configuring File System Storage Adapter

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/README.md

Sets up the Conversations plugin to use the file system for storing conversation state. Requires installing `@grammyjs/storage-file`.

```typescript
bot.use(conversations({
    storage: {
        type: "key",
        version: 0,
        adapter: new FileAdapter("./data"),
    },
}));
```

--------------------------------

### Plugin Installation: conversations()

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/README.md

Installs the conversations plugin middleware into your grammY bot. Options can be provided for configuration.

```typescript
bot.use(conversations(options));

```

--------------------------------

### Low-Level Replay Usage Example

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/engine.md

Demonstrates the low-level usage of `ReplayEngine` to manage conversational flows, including handling interrupts, performing actions, and replaying states.

```typescript
const engine = new ReplayEngine(async (controls) => {
    // Get user input
    const msg = await controls.interrupt("user_message");
    console.log("User said:", msg);
    
    // Perform database operation (side-effect)
    const stored = await controls.action(async () => {
        return await db.save(msg);
    }, "db_save");
    
    console.log("Stored with ID:", stored.id);
});

// First execution
let result = await engine.play();
// Output: type=interrupted, interrupts=[0]

if (result.type === "interrupted") {
    // Supply user message and resume
    ReplayEngine.supply(result.state, 0, "Hello!");
    result = await engine.replay(result.state);
    // Output: 
    // User said: Hello!
    // Stored with ID: 42
}

// If we replay again, same state
result = await engine.replay(result.state);
// Output:
// User said: Hello!
// Stored with ID: 42
// (db_save not called again - replayed from log)
```

--------------------------------

### Menu with Dynamic Content Example

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/README.md

Demonstrates creating a menu where button text updates dynamically based on user selection. The menu re-renders when `ctx.menu.update()` is called.

```typescript
async function menuExample(conversation, ctx) {
    let selected = "";
    
    const menu = conversation.menu()
        .text(() => selected || "Choose", ctx => ctx.menu.update())
        .row()
        .text("Option A", ctx => {
            selected = "Option A";
            ctx.menu.update();
        })
        .text("Option B", ctx => {
            selected = "Option B";
            ctx.menu.update();
        });
    
    await ctx.reply("Select:", { reply_markup: menu });
    await conversation.wait();
}
```

--------------------------------

### Custom Form Field Example

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/forms.md

An example demonstrating how to use the `build` method to create a form field that only accepts even numbers.

```typescript
const even = await conversation.form.build({
    validate: (ctx) => {
        const text = ctx.message?.text;
        if (!text) return { ok: false };
        const num = parseInt(text);
        if (num % 2 !== 0) return { ok: false };
        return { ok: true, value: num };
    },
    otherwise: ctx => ctx.reply("Please send an even number!"),
});
```

--------------------------------

### Install Default Plugins for All Conversations

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/setup.md

Use this snippet to configure default plugins that will run on every context within conversations. Ensure the `conversations` plugin is imported and used.

```typescript
bot.use(conversations({
    plugins: [
        // Plugins to run in all conversations
        async (ctx, next) => {
            console.log("User:", ctx.from?.first_name);
            await next();
        },
    ],
}));
```

--------------------------------

### File System Storage Adapter

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/storage.md

An example implementation of VersionedStateStorage using the Node.js file system. Stores conversation data as JSON files.

```typescript
import { readFile, writeFile, unlink } from "fs/promises";
import { join } from "path";

const fileAdapter: VersionedStateStorage<string, ConversationData> = {
    directory: "./data",
    
    async read(key) {
        try {
            const data = await readFile(
                join(this.directory, `${key}.json`),
                "utf-8"
            );
            return JSON.parse(data);
        } catch {
            return undefined;
        }
    },
    
    async write(key, state) {
        await writeFile(
            join(this.directory, `${key}.json`),
            JSON.stringify(state)
        );
    },
    
    async delete(key) {
        await unlink(join(this.directory, `${key}.json`));
    },
};
```

--------------------------------

### In-Memory Storage Adapter

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/storage.md

An example implementation of VersionedStateStorage using a Map for in-memory storage. Suitable for development or temporary data.

```typescript
const memoryAdapter: VersionedStateStorage<string, ConversationData> = {
    store: new Map(),
    
    read(key) {
        return this.store.get(key);
    },
    
    write(key, state) {
        this.store.set(key, state);
    },
    
    delete(key) {
        this.store.delete(key);
    },
};
```

--------------------------------

### File System Storage Adapter for Conversations

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/setup.md

Implement a custom file system adapter for persistent storage of conversation states. This example uses Node.js 'fs/promises' to read and write conversation data to files.

```typescript
import { readFile, writeFile, mkdir } from "fs/promises";
import { join } from "path";

const dataDir = "./data";

const fileAdapter = {
    async read(key: string) {
        try {
            const content = await readFile(
                join(dataDir, `${key}.json`),
                "utf-8"
            );
            return JSON.parse(content);
        } catch {
            return undefined;
        }
    },

    async write(key: string, value: any) {
        await mkdir(dataDir, { recursive: true });
        await writeFile(
            join(dataDir, `${key}.json`),
            JSON.stringify(value, null, 2)
        );
    },

    async delete(key: string) {
        try {
            await unlink(join(dataDir, `${key}.json`));
        } catch {
            // Already deleted
        }
    },
};

bot.use(conversations({
    storage: {
        type: "key",
        version: 1,
        adapter: fileAdapter,
    },
}));
```

--------------------------------

### now() Method

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/conversation.md

Gets the current timestamp, ensuring consistency across conversation replays. This is useful for time-sensitive operations.

```APIDOC
## now() Method

Gets the current timestamp, consistent across replays.

```typescript
async now(): Promise<number>
```

### Returns

Current time in milliseconds (from `Date.now()`).

### Usage Example

```typescript
const startTime = await conversation.now();
// ... wait for updates ...
const endTime = await conversation.now();
console.log(`Elapsed: ${endTime - startTime}ms`);
```
```

--------------------------------

### conversations()

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/api-reference.md

Installs the conversations plugin middleware on a grammY bot. It can be configured with options for storage, plugins, and callbacks for entering/exiting conversations.

```APIDOC
## conversations()

### Description
Installs the conversations plugin middleware on a grammY bot.

### Method
`bot.use()`

### Parameters
#### Options
- **options** (ConversationOptions<OC, C>) - Optional - Configuration options for the plugin.
  - **storage** (ConversationStorage<OC, ConversationData>) - Optional - Persistence layer for conversation state. Defaults to an in-memory map.
  - **plugins** (Middleware<C>[] | ((conversation: Conversation<OC, C>) => Middleware<C>[] | Promise<Middleware<C>[]>) ) - Optional - Default plugins installed for all conversations. Defaults to `[]`.
  - **onEnter** ((id: string, ctx: OC) => unknown | Promise<unknown>) - Optional - Callback when entering a conversation.
  - **onExit** ((id: string, ctx: OC) => unknown | Promise<unknown>) - Optional - Callback when exiting a conversation.

### Returns
A middleware function that can be installed via `bot.use()`.

### Usage Example
```typescript
import { Bot, Context } from "grammy";
import { conversations, createConversation, ConversationFlavor } from "@grammyjs/conversations";

type MyContext = ConversationFlavor<Context>;

const bot = new Bot<MyContext>("");

// Install with default options (in-memory storage)
bot.use(conversations());

// Or with storage and callbacks
bot.use(conversations({
    storage: {
        type: "key",
        version: 0,
        adapter: customStorageAdapter,
    },
    onEnter: (id, ctx) => console.log(`Entered: ${id}`),
    onExit: (id, ctx) => console.log(`Exited: ${id}`),
}));
```
```

--------------------------------

### Simple Form Collection Example

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/README.md

Collects user input for name and age using `conversation.form.text` and `conversation.form.int`. Includes an `otherwise` handler for invalid input.

```typescript
async function userForm(conversation, ctx) {
    await ctx.reply("Tell me about yourself");
    
    const name = await conversation.form.text({
        otherwise: ctx => ctx.reply("Please send text!"),
    });
    
    const age = await conversation.form.int({
        otherwise: ctx => ctx.reply("Please send a number!"),
    });
    
    await ctx.reply(`${name} is ${age} years old`);
}
```

--------------------------------

### Official File System Storage Package for Conversations

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/setup.md

Use the official '@grammyjs/storage-file' package for file system-based persistent storage. This simplifies the setup compared to a custom adapter.

```typescript
import { FileAdapter } from "@grammyjs/storage-file";

bot.use(conversations({
    storage: {
        type: "key",
        version: 1,
        adapter: new FileAdapter("./data"),
    },
}));
```

--------------------------------

### play() Method

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/engine.md

Begins a new execution from scratch.

```APIDOC
## play() Method

Begins a new execution from scratch.

```typescript
async play(): Promise<ReplayResult>
```

**Returns:** A `ReplayResult` indicating completion, error, or interruption

**Example:**
```typescript
const result = await engine.play();
if (result.type === "interrupted") {
    const state = result.state;
    const interrupts = result.interrupts;
}
```
```

--------------------------------

### Conversation Control: Entering a Conversation

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/README.md

Starts a specific conversation by its ID. Additional arguments can be passed to the conversation function.

```typescript
ctx.conversation.enter(id, ...args)

```

--------------------------------

### Simple Storage Configuration

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/storage.md

For backwards compatibility, a raw VersionedStateStorage can be passed directly, which is implicitly treated as key-based storage.

```typescript
const storage: VersionedStateStorage<string, ConversationData> = {
    async read(key) { /* ... */ },
    async write(key, state) { /* ... */ },
    async delete(key) { /* ... */ },
};

bot.use(conversations({ storage }));
// Automatically treated as { type: "key", adapter: storage }
```

--------------------------------

### Check Active Conversations

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/setup.md

Get a list of currently active conversations using `ctx.conversation.active()`. This can be used for status checks or debugging.

```typescript
bot.command("status", (ctx) => {
    const active = ctx.conversation.active();
    await ctx.reply(`Active: ${JSON.stringify(active)}`);
});
```

--------------------------------

### audio()

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/forms.md

Waits for audio.

```APIDOC
## audio()

### Description
Waits for audio.

### Method
`async audio(options?: FormOptions<C, Audio>): Promise<Audio>`
```

--------------------------------

### video()

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/forms.md

Waits for a video.

```APIDOC
## video()

### Description
Waits for a video.

### Method
`async video(options?: FormOptions<C, Video>): Promise<Video>`
```

--------------------------------

### menu() Method

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/conversation.md

Creates a conversational menu, typically displayed as an inline keyboard. This method allows for interactive user choices within the conversation.

```APIDOC
## menu() Method

Creates a conversational menu (inline keyboard).

```typescript
menu(id?: string, options?: Partial<ConversationMenuOptions<C>>): ConversationMenu<C>
```

### Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| id | `string` | No | Optional menu identifier |
| options | `Partial<ConversationMenuOptions<C>>` | No | Menu configuration |

### Returns

A `ConversationMenu<C>` instance.

### Usage Example

```typescript
const menu = conversation.menu()
    .text("Option A", ctx => ctx.reply("You chose A"))
    .row()
    .text("Option B", ctx => ctx.reply("You chose B"));

await ctx.reply("Choose one:", { reply_markup: menu });
```
```

--------------------------------

### random() Method

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/conversation.md

Gets a random number, ensuring consistency across conversation replays. This is useful for operations requiring reproducible randomness.

```APIDOC
## random() Method

Gets a random number, consistent across replays.

```typescript
async random(): Promise<number>
```

### Returns

A random number between 0 and 1 (from `Math.random()`).
```

--------------------------------

### Typical Form Usage Pattern

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/forms.md

Illustrates a common pattern for using forms in sequences to collect user information step-by-step.

```typescript
async function userForm(conversation, ctx) {
    await ctx.reply("Let's collect your info!");
    
    const name = await conversation.form.text({
        otherwise: ctx => ctx.reply("What's your name?"),
    });
    
    const age = await conversation.form.int({
        otherwise: ctx => ctx.reply("What's your age?"),
    });
    
    const country = await conversation.form.select(["US", "UK", "Other"], {
        otherwise: ctx => ctx.reply("Choose a country"),
    });
    
    await ctx.reply(
        `Got it: ${name}, ${age} years old, from ${country}`
    );
}
```

--------------------------------

### Get counts of all active conversations

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/api-reference.md

Returns an object with counts of active conversations for each conversation name. This provides an overview of ongoing conversations.

```typescript
active(): Record<string, number>
```

--------------------------------

### ReplayEngine Constructor

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/engine.md

Creates a new replay engine from a builder function.

```APIDOC
## Constructor

```typescript
constructor(builder: Builder)
```

Creates a new replay engine from a builder function.

### Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| builder | `Builder` | Function to execute and replay |

**Builder Signature:**

```typescript
type Builder = (controls: ReplayControls) => void | Promise<void>
```

The builder receives a `ReplayControls` object for controlling execution.

### Usage Example

```typescript
const engine = new ReplayEngine(async (controls) => {
    const value = await controls.interrupt("first");
    console.log(value);
    
    const result = await controls.action(() => {
        return Math.random();
    }, "random");
    
    console.log(result);
});
```
```

--------------------------------

### ReplayEngine Static Methods

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/engine.md

Static methods for managing replay states.

```APIDOC
## Static Methods

### open(key)

Creates initial replay state with an unresolved interrupt.

```typescript
static open(key: string): [ReplayState, number]
```

**Parameters:**
- `key` - Collation key for the first interrupt

**Returns:** Tuple of `[initialState, interruptId]`

**Purpose:** Creates a starting point to replay a function multiple times with different inputs.

**Example:**
```typescript
const [state, interrupt] = ReplayEngine.open("user-input");

// Supply a value for the interrupt
ReplayEngine.supply(state, interrupt, userMessage);

// Replay will now resolve the interrupt with the supplied value
const result = await engine.replay(state);
```

### supply(state, interrupt, value)

Supplies a value for an interrupt in the replay state.

```typescript
static supply(
    state: ReplayState, 
    interrupt: number, 
    value: unknown
): Checkpoint
```

**Parameters:**
- `state` - The replay state to mutate
- `interrupt` - The interrupt ID from a previous execution
- `value` - The value to supply to that interrupt

**Returns:** A `Checkpoint` that can be used to undo this mutation

**Example:**
```typescript
const [state, int] = ReplayEngine.open("request");

// First time: supplies "hello" to the interrupt
ReplayEngine.supply(state, int, "hello");
let result1 = await engine.replay(state);

// Reset to before the supply
ReplayEngine.reset(state, checkpoint);

// Second time: supplies "goodbye"
ReplayEngine.supply(state, int, "goodbye");
let result2 = await engine.replay(state);
```

### reset(state, checkpoint)

Resets a replay state to a previously recorded checkpoint.

```typescript
static reset(state: ReplayState, checkpoint: Checkpoint): void
```

**Parameters:**
- `state` - The replay state to mutate
- `checkpoint` - A checkpoint from `supply()` or `controls.checkpoint()`

**Effect:** Mutates the state to remove all mutations after the checkpoint.
```

--------------------------------

### game()

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/forms.md

Waits for a game.

```APIDOC
## game()

### Description
Waits for a game.

### Method
`async game(options?: FormOptions<C, Game>): Promise<Game>`
```

--------------------------------

### Get Consistent Timestamp

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/conversation.md

Obtain a consistent timestamp across replays using `conversation.now()`. This is useful for measuring durations or time-sensitive operations within a conversation.

```typescript
const startTime = await conversation.now();
// ... wait for updates ...
const endTime = await conversation.now();
console.log(`Elapsed: ${endTime - startTime}ms`);
```

--------------------------------

### Redis Storage Adapter for Conversations

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/setup.md

Set up persistent storage for conversations using Redis with the '@grammyjs/storage-redis' package. Requires a running Redis instance.

```typescript
import { RedisAdapter } from "@grammyjs/storage-redis";
import { createClient } from "redis";

const redis = createClient();

bot.use(conversations({
    storage: {
        type: "key",
        version: 1,
        adapter: new RedisAdapter({ client: redis }),
    },
}));
```

--------------------------------

### Get Consistent Random Number

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/conversation.md

Generate a consistent random number between 0 and 1 using `conversation.random()`. This ensures that random choices are reproducible during conversation replays.

```typescript
async random(): Promise<number>
```

--------------------------------

### photo()

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/forms.md

Waits for a photo and returns an array of `PhotoSize` objects.

```APIDOC
## photo()

### Description
Waits for a photo.

### Method
`async photo(options?: FormOptions<C, PhotoSize[]>): Promise<PhotoSize[]>`

### Returns
Array of `PhotoSize` objects
```

--------------------------------

### checkpoint()

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/engine.md

Creates a snapshot of the current execution position. This snapshot can be used later to reset the replay engine to a specific point in the execution flow.

```APIDOC
## checkpoint()

### Description
Creates a snapshot of current execution position. This snapshot can be used with `ReplayEngine.reset()` to rewind execution.

### Method
`checkpoint(): Checkpoint`

### Returns
- `Checkpoint` - A `Checkpoint` that can be used with `ReplayEngine.reset()`.

### Use Case
Save a point to rewind to later.

### Example
```typescript
const checkpoint1 = controls.checkpoint();
const data1 = await controls.action(() => fetchData(), "fetch1");

// Decide to rewind
ReplayEngine.reset(state, checkpoint1);

// Execution continues from before checkpoint1
```
```

--------------------------------

### Add Text Buttons to a Menu

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/menus.md

Add text buttons to a menu. Buttons can trigger replies or menu updates. Use `.row()` to start a new row.

```typescript
menu.text("Click me", ctx => ctx.reply("You clicked!"))
    .row()
    .text("Or me", 
        ctx => ctx.reply("You clicked this one!"),
        ctx => ctx.menu.update()
    );
```

--------------------------------

### ContextBaseData for Context Creation

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/types.md

Provides the minimal context data required to construct new context objects, including the update, API configuration, and bot's user information.

```typescript
interface ContextBaseData {
    update: Update;
    api: ApiBaseData;
    me: UserFromGetMe;
}
```

--------------------------------

### Create a Conversational Menu

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/menus.md

Create a new conversational menu with a unique identifier and optional configuration. Use `conversation.menu()` to instantiate.

```typescript
const menu = conversation.menu("my-menu", {
    parent: "root-menu",
    autoAnswer: true,
    fingerprint: ctx => JSON.stringify(ctx.from?.id),
});
```

--------------------------------

### Get count of active conversations by name

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/api-reference.md

Returns the count of active conversations with a given name. Use this to check how many instances of a specific conversation are currently running.

```typescript
active(name: string): number
```

--------------------------------

### select()

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/forms.md

Waits for text matching one of several predefined strings and returns the matched string.

```APIDOC
## select()

### Description
Waits for text matching one of several predefined strings.

### Method
`async select<E extends string>(entries: E[], options?: FormOptions<C, E>): Promise<E>`

### Parameters
- `entries` (string[]) - Required - Array of valid strings to match

### Returns
The matched string

### Example
```typescript
const choice = await conversation.form.select(["Yes", "No"], {
    otherwise: ctx => ctx.reply("Please choose Yes or No!")
});

if (choice === "Yes") {
    // ...
}
```
```

--------------------------------

### ConversationOptions Configuration

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/types.md

Configure the `conversations()` plugin using `ConversationOptions`. This allows setting up storage, plugins, and callbacks for entering/exiting conversations.

```typescript
interface ConversationOptions<OC extends Context, C extends Context> {
    storage?: ConversationStorage<OC, ConversationData>;
    plugins?: Middleware<C>[] | ((conversation: Conversation<OC, C>) => 
        Middleware<C>[] | Promise<Middleware<C>[]>);
    onEnter?(id: string, ctx: OC): unknown | Promise<unknown>;
    onExit?(id: string, ctx: OC): unknown | Promise<unknown>;
}
```

--------------------------------

### Configure Per-Conversation Plugins

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/setup.md

Set up plugins that are specific to a single conversation. This is useful for logic that should only apply within a particular conversation flow. Use `createConversation` to define the conversation and its specific plugins.

```typescript
bot.use(createConversation(myConversation, {
    id: "my-convo",
    plugins: [
        // Only in this conversation
        async (ctx, next) => {
            console.log("In myConversation");
            await next();
        },
    ],
}));
```

--------------------------------

### Chaining Filters with AndPromise

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/conversation.md

Chain multiple filters to a conversation.wait() call to precisely control the conditions under which the conversation proceeds. This example demonstrates filtering by message text length, message type, command, and sender ID.

```typescript
const ctx = await conversation.wait()
    .and(ctx => ctx.msg?.text?.length > 5)
    .andFor(":text")
    .andForCommand("start")
    .andFrom(userId);
```

--------------------------------

### video_note()

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/forms.md

Waits for a video note.

```APIDOC
## video_note()

### Description
Waits for a video note.

### Method
`async video_note(options?: FormOptions<C, VideoNote>): Promise<VideoNote>`
```

--------------------------------

### ApiBaseData for API Instances

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/types.md

Contains essential information for constructing API instances, such as the bot token and optional API client configurations.

```typescript
interface ApiBaseData {
    token: string;
    options?: ApiClientOptions;
}
```

--------------------------------

### story()

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/forms.md

Waits for a story.

```APIDOC
## story()

### Description
Waits for a story.

### Method
`async story(options?: FormOptions<C, Story>): Promise<Story>`
```

--------------------------------

### replay() Method

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/engine.md

Resumes execution based on a saved state.

```APIDOC
## replay() Method

Resumes execution based on a saved state.

```typescript
async replay(state: ReplayState): Promise<ReplayResult>
```

**Parameters:**
- `state` - A previously created replay state

**Returns:** A `ReplayResult` with the outcome

**Example:**
```typescript
let state = (await engine.play() as Interrupted).state;

// Supply an interrupt value
const checkpoint = ReplayEngine.supply(state, 0, "hello");

// Replay with the new value
const result = await engine.replay(state);
```
```

--------------------------------

### enterConversation()

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/api-reference.md

Begins a new conversation execution from scratch. This function is used internally by the plugin to initiate a conversation flow.

```APIDOC
## enterConversation() Function

Begins a new conversation execution from scratch.

### Parameters

- `conversation` (`ConversationBuilder<OC, C>`): The conversation function.
- `base` (`ContextBaseData`): Update and API info.
- `options` (`EnterOptions<OC, C>`): Additional options including args.

### Returns

An `EnterResult` indicating the outcome of the conversation entry.
```

--------------------------------

### ReplayEngine Constructor

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/engine.md

Creates a new replay engine instance. The builder function provided will be executed and can be replayed.

```typescript
constructor(builder: Builder)
```

--------------------------------

### Add Login Button to a Menu

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/menus.md

Add a button that initiates a login flow. Requires a URL string or a `LoginUrl` object.

```typescript
menu.login("Login", "https://example.com/login");
```

--------------------------------

### ConversationMenuOptions

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/menus.md

Configuration options for creating a `ConversationMenu`. These options define the menu's behavior, parent menu for navigation, and how its state is identified.

```APIDOC
## ConversationMenuOptions

Configuration when creating a menu:

```typescript
interface ConversationMenuOptions<C extends Context> {
    parent?: string | { id: string };
    autoAnswer: boolean;
    fingerprint: (ctx: C) => string | Promise<string>;
}
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| parent | string \| object | undefined | Parent menu ID for back navigation |
| autoAnswer | boolean | true | Automatically call `ctx.answerCallbackQuery()` |
| fingerprint | function | `() => ""` | Generate unique identifier for menu state |
```

--------------------------------

### Add Web App Button to a Menu

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/menus.md

Add a button that opens a web app. The URL must be an HTTPS URL.

```typescript
menu.webApp("Open Web App", "https://example.com/webapp");
```

--------------------------------

### ReplayEngine Class

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/engine.md

Controls execution replay of builder functions.

```APIDOC
## ReplayEngine Class

Controls execution replay of builder functions.

```typescript
class ReplayEngine {
    constructor(builder: Builder);
    async play(): Promise<ReplayResult>;
    async replay(state: ReplayState): Promise<ReplayResult>;
    static open(key: string): [ReplayState, number];
    static supply(state: ReplayState, interrupt: number, value: unknown): Checkpoint;
    static reset(state: ReplayState, checkpoint: Checkpoint): void;
}
```
```

--------------------------------

### HaltOptions

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/types.md

Options for the `halt()` function.

```APIDOC
## HaltOptions

### Description
Options for the `halt()` function.

### Type Definition
```typescript
interface HaltOptions {
    next?: boolean;
}
```

### Fields
- **next** (`boolean`) - Optional - Call downstream middleware
```

--------------------------------

### sticker()

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/forms.md

Waits for a sticker.

```APIDOC
## sticker()

### Description
Waits for a sticker.

### Method
`async sticker(options?: FormOptions<C, Sticker>): Promise<Sticker>`
```

--------------------------------

### Version Management with pinVersion

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/storage.md

Helper function to manage data versioning for schema changes. Use `versionify` before storing and `unpack` after loading.

```typescript
import { pinVersion } from "@grammyjs/conversations";

const { versionify, unpack } = pinVersion(0);

// Add version to data before storing
const versioned = versionify(myData);
await adapter.write(key, versioned);

// Remove version when loading
const loaded = await adapter.read(key);
const data = unpack(loaded); // returns undefined if version mismatch
```

--------------------------------

### Add Game Button to a Menu

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/menus.md

Add a button to launch a game. This button must be the first in the first row.

```typescript
menu.game("Play Game");
```

--------------------------------

### Menu Methods for Building Interactive Menus

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/README.md

Defines various methods for creating buttons, navigation, layout, and sending menus within a conversation. Use these to construct rich, interactive user interfaces.

```typescript
const menu = conversation.menu(id, options);

// Buttons
menu.text(text, ...handlers)
menu.url(text, url)
menu.webApp(text, url)
menu.login(text, loginUrl)
menu.game(text)
menu.pay(text)
menu.copyText(text, data)
menu.switchInline(text, query)
menu.switchInlineCurrent(text, query)
menu.switchInlineChosen(text, query)

// Navigation
menu.submenu(text, targetMenu, ...handlers)
menu.back(text, ...handlers)

// Layout
menu.row()
menu.append(range)
menu.dynamic(factory)

// Send menu
await ctx.reply("Choose:", { reply_markup: menu });
```

--------------------------------

### Implement Dynamic Plugins Based on Conversation State

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/setup.md

Configure plugins that can be dynamically determined based on the conversation's state. This allows for more flexible plugin behavior. The `plugins` option can accept an async function that returns an array of plugins.

```typescript
bot.use(conversations({
    plugins: async (conversation) => {
        // Can access conversation here
        return [
            async (ctx, next) => {
                await next();
            },
        ];
    },
}));
```

--------------------------------

### checkpoint() Method

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/conversation.md

Creates a checkpoint to save the current execution point in the conversation. This checkpoint can later be used to rewind the conversation's state.

```APIDOC
## checkpoint() Method

Creates a checkpoint to save the current execution point.

```typescript
checkpoint(): Checkpoint
```

### Returns

A `Checkpoint` that can be passed to `rewind()`.

### Usage Example

```typescript
const checkpoint = conversation.checkpoint();
// ... do some work ...
if (shouldRevert) {
    await conversation.rewind(checkpoint);
}
```
```

--------------------------------

### contact()

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/forms.md

Waits for a contact.

```APIDOC
## contact()

### Description
Waits for a contact.

### Method
`async contact(options?: FormOptions<C, Contact>): Promise<Contact>`
```

--------------------------------

### ConversationMenuRange Class Methods

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/menus.md

Methods for building menu ranges, including adding buttons, arranging them in rows, appending other menus, and creating dynamic content. All methods return `this` for chaining.

```APIDOC
## ConversationMenuRange Class

Base class for menu building with button layout methods.

```typescript
class ConversationMenuRange<C extends Context>
```

All button and layout methods return `this` for method chaining.

### back()

Adds a back button to parent menu.

```typescript
back(
    text: MaybeDynamicString<C>,
    ...middleware: ConversationMenuMiddleware<C>[]
): this
```

**Parameters:**
- `text` - Button label
- `middleware` - Handlers before navigation

**Requires:** Parent menu to be set via `{ parent: "..." }` option

### row()

Adds a line break, moving subsequent buttons to the next row.

```typescript
row(): this
```

**Example:**
```typescript
menu.text("A").text("B")
    .row()
    .text("C").text("D");
// Results in:
// [A] [B]
// [C] [D]
```

### append()

Appends another menu range or raw button array.

```typescript
append(range: MaybeRawRange<C>): this
```

**Example:**
```typescript
menu.append([
    [{ text: "Button 1", callback_data: "1" }],
    [{ text: "Button 2", callback_data: "2" }],
]);
```

### dynamic()

Creates dynamic menu content based on context.

```typescript
dynamic(
    rangeBuilder: (ctx: C, range: ConversationMenuRange<C>) => 
        MaybePromise<MaybeRawRange<C> | void>
): this
```

**Example:**
```typescript
const users = await conversation.external(() => db.getUsers());

menu.dynamic((ctx, range) => {
    users.forEach(user => {
        range.text(`User: ${user.name}`, 
            ctx => ctx.reply(`Selected ${user.name}`));
    });
});
```
```

--------------------------------

### Navigate to Parent Menu

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/menus.md

Navigates back to the parent menu. This is a shortcut for `ctx.menu.nav({ id: "parent-menu-id" })`.

```typescript
ctx.menu.back()
```

--------------------------------

### SkipOptions

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/types.md

Options for the `skip()` function, with an optional boolean to control calling downstream middleware.

```APIDOC
## SkipOptions

### Description
Options for the `skip()` function, with an optional boolean to control calling downstream middleware.

### Type Definition
```typescript
interface SkipOptions {
    next?: boolean;
}
```

### Fields
- **next** (`boolean`) - Optional - Call downstream middleware
```

--------------------------------

### ConversationContextStorage<C, S>

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/types.md

Defines a context-based storage backend for conversations.

```APIDOC
## Interface ConversationContextStorage<C, S>

### Description
Defines a context-based storage backend for conversations.

### Properties
- **type**: "context" - Identifies this as context-based storage.
- **version?**: string | number - Optional version for the storage.
- **adapter**: VersionedStateStorage<C, S> - The underlying adapter for storing versioned states using the context itself as the key.

### Type Definition
```typescript
interface ConversationContextStorage<C extends Context, S> {
    type: "context";
    version?: string | number;
    adapter: VersionedStateStorage<C, S>;
}
```
```

--------------------------------

### WaitOptions

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/types.md

Options passed to the `wait()` function, including an optional timeout and a collation key for replay validation.

```APIDOC
## WaitOptions

### Description
Options passed to the `wait()` function, including an optional timeout and a collation key for replay validation.

### Type Definition
```typescript
interface WaitOptions {
    maxMilliseconds?: number;
    collationKey?: string;
}
```

### Fields
- **maxMilliseconds** (`number`) - Optional - Timeout before halting
- **collationKey** (`string`) - Optional - Safety key for replay validation
```

--------------------------------

### Dynamic Menu Content with Fingerprint

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/menus.md

Shows how to integrate conversational menus with outside menus using a custom fingerprint for dynamic content. The fingerprint ensures correct menu state identification.

```typescript
const fingerprint = ctx => {
    // Return a unique ID based on current state
    return JSON.stringify({ userId: ctx.from?.id, count });
};

menu.dynamic((ctx, range) => {
    // Dynamic content
}, { fingerprint });
```

--------------------------------

### Single Context Type Strategy

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/setup.md

Use a single context type that includes ConversationFlavor. This is the recommended approach for simpler bots.

```typescript
type MyContext = ConversationFlavor<Context>;

bot.use(conversations());
```

--------------------------------

### voice()

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/forms.md

Waits for a voice message.

```APIDOC
## voice()

### Description
Waits for a voice message.

### Method
`async voice(options?: FormOptions<C, Voice>): Promise<Voice>`
```

--------------------------------

### Create Dynamic Menu Content

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/menus.md

Creates dynamic menu content based on the provided context and range builder function. This allows menu items to be generated at runtime.

```typescript
dynamic(
    rangeBuilder: (ctx: C, range: ConversationMenuRange<C>) => 
        MaybePromise<MaybeRawRange<C> | void>
): this
```

```typescript
const users = await conversation.external(() => db.getUsers());

menu.dynamic((ctx, range) => {
    users.forEach(user => {
        range.text(`User: ${user.name}`, 
            ctx => ctx.reply(`Selected ${user.name}`));
    });
});
```

--------------------------------

### document()

Source: https://github.com/grammyjs/conversations/blob/main/_autodocs/forms.md

Waits for a document.

```APIDOC
## document()

### Description
Waits for a document.

### Method
`async document(options?: FormOptions<C, Document>): Promise<Document>`
```