grammY

https://grammy.dev/
Admin
grammY is an easy-to-use, flexible, and scalable Telegram Bot Framework for building bots with...
Tokens:479,845
Snippets:6,047
Trust Score:8.5
Update:1 day ago
Show doc for...
Tokens:
Raw
### Construct the start command

Source: https://grammy.dev/hosting/vps

The start command format is `<runtime_path> <options> <entry_file_relative_path>`. The example shows the format with comments and examples for Deno and Node.js.

```sh
<runtime_path> <options> <entry_file_relative_path>

# Path to the bot directory: /home/user/bot1/

# Deno example:
# /home/user/.deno/bin/deno --allow-all run mod.ts

# Node.js example:
# /home/user/.nvm/versions/node/v16.9.1/bin/node index.js
```

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

### Simple installation (JavaScript)

Source: https://grammy.dev/plugins/hydrate

JavaScript setup for the simple installation, using bot.use(hydrate()).

```js
import { Bot } from "grammy";
import { hydrate } from "@grammyjs/hydrate";

const bot = new Bot("");

bot.use(hydrate());
```

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

### Simple installation (TypeScript)

Source: https://grammy.dev/plugins/hydrate

TypeScript setup for the simple installation, using HydrateFlavor and bot.use(hydrate()).

```ts
import { Bot, Context } from "grammy";
import { hydrate, HydrateFlavor } from "@grammyjs/hydrate";

type MyContext = HydrateFlavor<Context>;

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

bot.use(hydrate());
```

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

### Quickstart conversation example (TypeScript)

Source: https://grammy.dev/plugins/conversations

TypeScript example of the conversations plugin quickstart. It defines a 'hello' conversation that replies, waits for a text message, and replies again. Requires a bot token and the @grammyjs/conversations package.

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

const bot = new Bot<ConversationFlavor<Context>>(""); // <-- put your bot token between the "" (https://t.me/BotFather)
bot.use(conversations());

/** Defines the conversation */
async function hello(conversation: Conversation, ctx: Context) {
  await ctx.reply("Hi there! What is your name?");
  const { message } = await conversation.waitFor("message:text");
  await ctx.reply(`Welcome to the chat, ${message.text}!`);
}
bot.use(createConversation(hello));

bot.command("enter", async (ctx) => {
  // Enter the function "hello" you declared.
  await ctx.conversation.enter("hello");
});

bot.start();
```

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

### Simple installation (Deno)

Source: https://grammy.dev/plugins/hydrate

Deno setup for the simple installation, using npm: imports and HydrateFlavor.

```ts
import { Bot, Context } from "npm:grammy";
import { hydrate, HydrateFlavor } from "npm:@grammyjs/hydrate";

type MyContext = HydrateFlavor<Context>;

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

bot.use(hydrate());
```

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

### package.json with start script

Source: https://grammy.dev/hosting/zeabur-nodejs

Example package.json with a start script using ts-node to run the bot. Includes dependencies and devDependencies.

```json
{
  "name": "telegram-bot-starter",
  "version": "1.0.0",
  "description": "Telegram Bot Starter with TypeScript and grammY",
  "scripts": {
    "start": "ts-node src/bot.ts"
  },
  "author": "MichaelYuhe",
  "license": "MIT",
  "dependencies": {
    "grammy": "^1.21.1"
  },
  "devDependencies": {
    "@types/node": "^20.14.5",
    "ts-node": "^10.9.2",
    "typescript": "^5.4.5"
  }
}
```

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

### Quickstart: Deno with stream plugin

Source: https://grammy.dev/plugins/stream

Same quickstart example for Deno, using npm: prefixed imports for grammY, auto-retry, and stream. Streams a slow text generator to a private chat with ctx.replyWithStream.

```TypeScript
import { Bot, type Context } from "npm:grammy";
import { autoRetry } from "npm:@grammyjs/auto_retry";
import { stream, type StreamFlavor } from "npm:@grammyjs/stream";

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

bot.api.config.use(autoRetry()); // strongly recommended!
bot.use(stream());

async function* slowText() {
  // emulate slow text generation
  yield "This is som";
  await new Promise((r) => setTimeout(r, 2000));
  yield "e slowly gen";
  await new Promise((r) => setTimeout(r, 2000));
  yield "erated text";
}

// Telegram only supports streaming in private chats.
bot.chatType("private")
  .command("stream", async (ctx) => {
    // Stream the message!
    await ctx.replyWithStream(slowText());
  });

bot.start();
```

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

### Quickstart: JavaScript (CommonJS) with stream plugin

Source: https://grammy.dev/plugins/stream

Same quickstart example in JavaScript using require() for grammY, auto-retry, and stream. Streams a slow text generator to a private chat with ctx.replyWithStream.

```JavaScript
const { Bot } = require("grammy");
const { autoRetry } = require("@grammyjs/auto-retry");
const { stream } = require("@grammyjs/stream");

const bot = new Bot("");

bot.api.config.use(autoRetry()); // strongly recommended!
bot.use(stream());

async function* slowText() {
  // emulate slow text generation
  yield "This is som";
  await new Promise((r) => setTimeout(r, 2000));
  yield "e slowly gen";
  await new Promise((r) => setTimeout(r, 2000));
  yield "erated text";
}

// Telegram only supports streaming in private chats.
bot.chatType("private")
  .command("stream", async (ctx) => {
    // Stream the message!
    await ctx.replyWithStream(slowText());
  });

bot.start();
```

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

### JavaScript quickstart bot

Source: https://grammy.dev/

Install grammY with npm and paste this code. Replace the empty string with your bot token from BotFather. The bot replies to any message with 'Hi there!' and starts polling.

```js
const { Bot } = require("grammy");

const bot = new Bot(""); // <-- put your bot token between the "" (https://t.me/BotFather)

// Reply to any message with "Hi there!".
bot.on("message", (ctx) => ctx.reply("Hi there!"));

bot.start();
```

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

### Advanced installation (JavaScript)

Source: https://grammy.dev/plugins/hydrate

JavaScript setup for the advanced installation, using hydrateContext and hydrateApi.

```js
import { Bot } from "grammy";
import { hydrateApi, hydrateContext } from "@grammyjs/hydrate";

const bot = new Bot("");

bot.use(hydrateContext());
bot.api.config.use(hydrateApi());
```

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

### Quickstart conversation example (Deno)

Source: https://grammy.dev/plugins/conversations

Deno version of the quickstart, using npm: specifiers for grammy and @grammyjs/conversations. Same behavior as the TypeScript version.

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

const bot = new Bot<ConversationFlavor<Context>>(""); // <-- put your bot token between the "" (https://t.me/BotFather)
bot.use(conversations());

/** Defines the conversation */
async function hello(conversation: Conversation, ctx: Context) {
  await ctx.reply("Hi there! What is your name?");
  const { message } = await conversation.waitFor("message:text");
  await ctx.reply(`Welcome to the chat, ${message.text}!`);
}
bot.use(createConversation(hello));

bot.command("enter", async (ctx) => {
  // Enter the function "hello" you declared.
  await ctx.conversation.enter("hello");
});

bot.start();
```

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

### Example of installing a transformer via plugins

Source: https://grammy.dev/ref/conversations/conversationconfig

This example shows how to use the plugins option to install a Bot API transformer on the context's API instance. Note that next resolves immediately, so plugins relying on post-next tasks won't work correctly.

```ts
plugins: [async (ctx, next) => {
  ctx.api.config.use(transformer)
  await next()
}]
```

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

### TypeScript quickstart bot

Source: https://grammy.dev/

Install grammY with npm and paste this code. Replace the empty string with your bot token from BotFather. The bot replies to any message with 'Hi there!' and starts polling.

```ts
import { Bot } from "grammy";

const bot = new Bot(""); // <-- put your bot token between the "" (https://t.me/BotFather)

// Reply to any message with "Hi there!".
bot.on("message", (ctx) => ctx.reply("Hi there!"));

bot.start();
```

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

### Basic bot example in JavaScript

Source: https://grammy.dev/guide/getting-started

Creates a bot instance with your token, registers handlers for the /start command and other messages, and starts the bot. Replace the empty string with your bot token.

```js
const { Bot } = require("grammy");

// Create an instance of the `Bot` class and pass your bot token to it.
const bot = new Bot(""); // <-- put your bot token between the ""

// You can now register listeners on your bot object `bot`.
// grammY will call the listeners when users send messages to your bot.

// Handle the /start command.
bot.command("start", (ctx) => ctx.reply("Welcome! Up and running."));
// Handle other messages.
bot.on("message", (ctx) => ctx.reply("Got another message!"));

// Now that you specified how to handle messages, you can start your bot.
// This will connect to the Telegram servers and wait for messages.

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

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

### Quickstart conversation example (JavaScript)

Source: https://grammy.dev/plugins/conversations

JavaScript (CommonJS) version of the quickstart. Uses require() for grammy and @grammyjs/conversations. Same behavior as the TypeScript version.

```js
const { Bot } = require("grammy");
const { conversations, createConversation } = require(
  "@grammyjs/conversations",
);

const bot = new Bot(""); // <-- put your bot token between the "" (https://t.me/BotFather)
bot.use(conversations());

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

bot.command("enter", async (ctx) => {
  // Enter the function "hello" you declared.
  await ctx.conversation.enter("hello");
});

bot.start();
```

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

### Advanced installation (TypeScript)

Source: https://grammy.dev/plugins/hydrate

TypeScript setup for the advanced installation, using hydrateContext and hydrateApi with API flavor.

```ts
import { Api, Bot, Context } from "grammy";
import {
  hydrateApi,
  HydrateApiFlavor,
  hydrateContext,
  HydrateFlavor,
} from "@grammyjs/hydrate";

type MyContext = HydrateFlavor<Context>;
type MyApi = HydrateApiFlavor<Api>;

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

bot.use(hydrateContext());
bot.api.config.use(hydrateApi());
```

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

### Install modules in bot.ts

Source: https://grammy.dev/advanced/structuring

Creates the bot instance, installs the `lists` module via `bot.use`, and starts the bot. Additional modules can be added similarly.

```ts
import { lists } from "./todo/list";

const bot = new Bot("");

bot.use(lists);
// ... maybe more modules like `todo` here

bot.start();
```

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

### Encoded webhook setup URL example

Source: https://grammy.dev/hosting/heroku

Example of the manual webhook URL with a bot token and an encoded webhook URL, showing how to percent-encode the URL.

```asciiart
https://api.telegram.org/botabcd:1234/setWebhook?url=https%3A%2F%2Fgrammybot.herokuapp.com%2Fsecret_path
```

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

### Emulator console output example

Source: https://grammy.dev/hosting/firebase

Example output showing the local URL of the cloud function after the emulators start.

```Shell
+  functions[us-central1-helloWorld]: http function initialized (http://127.0.0.1:5001/<firebase-projectname>/us-central1/helloWorld).
```

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

### Install Caddy with systemd

Source: https://grammy.dev/hosting/vps

Run these five commands to download and start Caddy as a systemd service named 'caddy'. Requires Debian-based system with apt.

```sh
apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | tee /etc/apt/sources.list.d/caddy-stable.list
apt update
apt install caddy
```

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

### Install storage adapter: session with storage option

Source: https://grammy.dev/plugins/session

Shows the general pattern for installing a storage adapter by passing a `storage` option to the `session` middleware. The `storageAdapter` variable depends on the chosen setup.

```TypeScript
const storageAdapter = ... // depends on setup

bot.use(session({
  initial: ...
  storage: storageAdapter,
}));
```

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

### Basic bot example in TypeScript

Source: https://grammy.dev/guide/getting-started

Creates a bot instance with your token, registers handlers for the /start command and other messages, and starts the bot. Replace the empty string with your bot token.

```ts
import { Bot } from "grammy";

// Create an instance of the `Bot` class and pass your bot token to it.
const bot = new Bot(""); // <-- put your bot token between the ""

// You can now register listeners on your bot object `bot`.
// grammY will call the listeners when users send messages to your bot.

// Handle the /start command.
bot.command("start", (ctx) => ctx.reply("Welcome! Up and running."));
// Handle other messages.
bot.on("message", (ctx) => ctx.reply("Got another message!"));

// Now that you specified how to handle messages, you can start your bot.
// This will connect to the Telegram servers and wait for messages.

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

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

### Using session middleware with bot.use

Source: https://grammy.dev/ref/core/composer

Example of using the use method to install session middleware on a bot instance.

```ts
bot.use(session())
```

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

### Deno quickstart bot

Source: https://grammy.dev/

For Deno, import grammY from npm. Replace the empty string with your bot token from BotFather. The bot replies to any message with 'Hi there!' and starts polling.

```ts
import { Bot } from "npm:grammy";

const bot = new Bot(""); // <-- put your bot token between the "" (https://t.me/BotFather)

// Reply to any message with "Hi there!".
bot.on("message", (ctx) => ctx.reply("Hi there!"));

bot.start();
```

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

### Setup i18n without sessions (Deno)

Source: https://grammy.dev/plugins/i18n

Deno example for setting up the i18n plugin without sessions. It uses npm: imports, extends the context with I18nFlavor, and includes a commented-out alternative for loading locales in Deno Deploy.

```TypeScript
import { Bot, Context } from "npm:grammy";
import { I18n, I18nFlavor } from "npm:@grammyjs/i18n";

// For TypeScript and auto-completion support,
// extend the context with I18n's flavor:
type MyContext = Context & I18nFlavor;

// Create a bot as you normally would.
// Remember to extend the context.
const bot = new Bot<MyContext>("");

// Create an `I18n` instance.
// Continue reading to find out how to configure the instance.
const i18n = new I18n<MyContext>({
  defaultLocale: "en", // see below for more information
  // Load all translation files from locales/. (Not working in Deno Deploy.)
  directory: "locales",
});

// Translation files loaded this way works in Deno Deploy, too.
// await i18n.loadLocalesDir("locales");

// Finally, register the i18n instance in the bot,
// so the messages get translated on their way!
bot.use(i18n);

// Everything is set up now.
// You can access translations with `t` or `translate`.
bot.command("start", async (ctx) => {
  await ctx.reply(ctx.t("start-msg"));
});
```

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

### Complete setup with custom context (TypeScript)

Source: https://grammy.dev/guide/context

Full example combining the custom context type, middleware to set the property, and a handler that uses it. This is the recommended way to customize the context object.

```TypeScript
const BOT_DEVELOPER = 123456; // bot developer chat identifier

// Define custom context type.
interface BotConfig {
  botDeveloper: number;
  isDeveloper: boolean;
}
type MyContext = Context & {
  config: BotConfig;
};

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

// Set custom properties on context objects.
bot.use(async (ctx, next) => {
  ctx.config = {
    botDeveloper: BOT_DEVELOPER,
    isDeveloper: ctx.from?.id === BOT_DEVELOPER,
  };
  await next();
});

// Define handlers for custom context objects.
bot.command("start", async (ctx) => {
  if (ctx.config.isDeveloper) await ctx.reply("Hi mom!");
  else await ctx.reply("Welcome");
});
```

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

### Final code example

Source: https://grammy.dev/guide/games

Combines the game button callback handler and the start command with an inline keyboard. The keyboard variable is assumed to be defined earlier.

```TypeScript
bot.on("callback_query:game_short_name", async (ctx) => {
  await ctx.answerCallbackQuery({ url: "your_game_url" });
});

bot.command("start", async (ctx) => {
  await ctx.replyWithGame("my_game", {
    reply_markup: keyboard,
    // Or you can use the api method here, according to your needs.
  });
});
```

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

### Create and send a simple menu (Deno)

Source: https://grammy.dev/plugins/menu

Example using Deno with grammY and @grammyjs/menu. Creates a menu with two text buttons, registers it as middleware, and sends it on the /start command. Ensure menus are installed before other middleware and include callback_query in allowed_updates if customized.

```TypeScript
import { Bot } from "npm:grammy";
import { Menu } from "npm:@grammyjs/menu";

// Create a bot.
const bot = new Bot("");

// Create a simple menu.
const menu = new Menu("my-menu-identifier")
  .text("A", (ctx) => ctx.reply("You pressed A!")).row()
  .text("B", (ctx) => ctx.reply("You pressed B!"));

// Make it interactive.
bot.use(menu);

bot.command("start", async (ctx) => {
  // Send the menu.
  await ctx.reply("Check out this menu:", { reply_markup: menu });
});

bot.start();
```

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

### Create and send a simple menu (JavaScript)

Source: https://grammy.dev/plugins/menu

Example using JavaScript with grammY and @grammyjs/menu. Creates a menu with two text buttons, registers it as middleware, and sends it on the /start command. Ensure menus are installed before other middleware and include callback_query in allowed_updates if customized.

```JavaScript
const { Bot } = require("grammy");
const { Menu } = require("@grammyjs/menu");

// Create a bot.
const bot = new Bot("");

// Create a simple menu.
const menu = new Menu("my-menu-identifier")
  .text("A", (ctx) => ctx.reply("You pressed A!")).row()
  .text("B", (ctx) => ctx.reply("You pressed B!"));

// Make it interactive.
bot.use(menu);

bot.command("start", async (ctx) => {
  // Send the menu.
  await ctx.reply("Check out this menu:", { reply_markup: menu });
});

bot.start();
```

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

### Create and send a simple menu (TypeScript)

Source: https://grammy.dev/plugins/menu

Example using TypeScript with grammY and @grammyjs/menu. Creates a menu with two text buttons, registers it as middleware, and sends it on the /start command. Ensure menus are installed before other middleware and include callback_query in allowed_updates if customized.

```TypeScript
import { Bot } from "grammy";
import { Menu } from "@grammyjs/menu";

// Create a bot.
const bot = new Bot("");

// Create a simple menu.
const menu = new Menu("my-menu-identifier")
  .text("A", (ctx) => ctx.reply("You pressed A!")).row()
  .text("B", (ctx) => ctx.reply("You pressed B!"));

// Make it interactive.
bot.use(menu);

bot.command("start", async (ctx) => {
  // Send the menu.
  await ctx.reply("Check out this menu:", { reply_markup: menu });
});

bot.start();
```

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

### Initialize project and create files

Source: https://grammy.dev/hosting/zeabur-deno

Commands to create a new project directory, create main.ts and deno.json files. Requires Deno installed locally.

```sh
# Initialize the project.
mkdir grammy-bot
cd grammy-bot

# Create main.ts file
touch main.ts

# Create deno.json file to generate lock file
touch deno.json
```

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

### Complete setup with custom context (JavaScript)

Source: https://grammy.dev/guide/context

JavaScript version of the complete setup. No type annotations are needed, but the same middleware and handler logic applies.

```JavaScript
const BOT_DEVELOPER = 123456; // bot developer chat identifier

const bot = new Bot("");

// Set custom properties on context objects.
bot.use(async (ctx, next) => {
  ctx.config = {
    botDeveloper: BOT_DEVELOPER,
    isDeveloper: ctx.from?.id === BOT_DEVELOPER,
  };
  await next();
});

// Define handlers for custom context objects.
bot.command("start", async (ctx) => {
  if (ctx.config.isDeveloper) await ctx.reply("Hi mom!");
  else await ctx.reply("Welcome");
});
```

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

### Advanced installation (Deno)

Source: https://grammy.dev/plugins/hydrate

Deno setup for the advanced installation, using npm: imports and both hydrateContext and hydrateApi.

```ts
import { Api, Bot, Context } from "npm:grammy";
import {
  hydrateApi,
  HydrateApiFlavor,
  hydrateContext,
  HydrateFlavor,
} from "npm:@grammyjs/hydrate";

type MyContext = HydrateFlavor<Context>;
type MyApi = HydrateApiFlavor<Api>;

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

bot.use(hydrateContext());
bot.api.config.use(hydrateApi());
```

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

### install

Source: https://grammy.dev/ref/conversations/conversationmenupool

Prepares a context object for supporting conversational menus. Returns a function to handle clicks.

```APIDOC
## install()

### Description
Prepares a context object for supporting conversational menus. Returns a function to handle clicks.

### Method
install

### Signature
```ts
install();
```

### Parameters
None

### Returns
- A function to handle clicks.
```

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

### Install a menu with bot.use

Source: https://grammy.dev/plugins/menu

Installs the menu so it becomes interactive. This must be done before sending the menu.

```TypeScript
bot.use(menu);
```

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

### Get Node.js runtime path

Source: https://grammy.dev/hosting/vps

Use `which node` to get the absolute path to the Node.js runtime, which is needed to construct the start command.

```sh
which node
```

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

### command() with start and help

Source: https://grammy.dev/ref/core/composer

Registers middleware for /start and /help commands.

```ts
// Reacts to /start commands
bot.command('start', ctx => { ... })
// Reacts to /help commands
bot.command('help', ctx => { ... })
```

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

### Get Deno runtime path

Source: https://grammy.dev/hosting/vps

Use `which deno` to get the absolute path to the Deno runtime, which is needed to construct the start command.

```sh
which deno
```

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

### Set up a new TypeScript project and install grammY with npm

Source: https://grammy.dev/guide/getting-started

Creates a new directory, initializes TypeScript, and installs grammY using npm. Run these commands in a terminal.

```sh
# Create a new directory and change into it.
mkdir my-bot
cd my-bot

# Set up TypeScript (skip if you use JavaScript).
npm install -D typescript
npx tsc --init

# Install grammY.
npm install grammy
```

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

### Install dependencies and initialize project

Source: https://grammy.dev/hosting/heroku

Commands to create a project directory, initialize npm, install grammy and express, install TypeScript and type definitions, and create a TypeScript config.

```sh
# Create a project directory.
mkdir grammy-bot
cd grammy-bot
npm init --y

# Install main dependencies.
npm install grammy express

# Install development dependencies.
npm install -D typescript @types/express @types/node

# Create TypeScript config.
npx tsc --init
```

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

### Create and start a bot

Source: https://grammy.dev/ref/core/bot

Shows the three essential steps to run a bot: create an instance with a secret token, listen for messages, and launch it.

```ts
// 1. Create a bot instance
const bot = new Bot('<secret-token>')
// 2. Listen for updates
bot.on('message:text', ctx => ctx.reply('You wrote: ' + ctx.message.text))
// 3. Launch it!
bot.start()
```

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

### Initialize project and install dependencies

Source: https://grammy.dev/hosting/zeabur-nodejs

Commands to create a new project directory, initialize npm, install grammy and development dependencies (typescript, ts-node, @types/node), and initialize TypeScript.

```sh
# Initialize the project.
mkdir grammy-bot
cd grammy-bot
npm init -y

# Install main dependencies.
npm install grammy

# Install development dependencies.
npm install -D typescript ts-node @types/node

# Initialize TypeScript.
npx tsc --init
```

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

### Define initial session data interface

Source: https://grammy.dev/plugins/session

An example of a session data interface that stores pet names as a string array. This is the starting point for the migration example.

```TypeScript
interface SessionData {
  petNames: string[];
}
```

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

### TypeScript setup for conversations (Deno)

Source: https://grammy.dev/plugins/conversations

Same setup as the Node.js example but uses Deno imports from 'npm:grammy' and 'npm:@grammyjs/conversations'. Defines the same context types and conversation function.

```TypeScript
import { Bot, type Context } from "npm:grammy";
import {
  type Conversation,
  type ConversationFlavor,
} from "npm:@grammyjs/conversations";

// Outside context objects (knows all middleware plugins)
type MyContext = ConversationFlavor<Context>;
// Inside context objects (knows all conversation plugins)
type MyConversationContext = Context;

// Use the outside context type for your bot.
const bot = new Bot<MyContext>(""); // <-- put your bot token between the "" (https://t.me/BotFather)

// Use both the outside and the inside type for your conversation.
type MyConversation = Conversation<MyContext, MyConversationContext>;

// Define your conversation.
async function example(
  conversation: MyConversation,
  ctx0: MyConversationContext,
) {
  // All context objects inside the conversation are
  // of type `MyConversationContext`.
  const ctx1 = await conversation.wait();

  // The outside context object can be accessed
  // via `conversation.external` and it is inferred to be
  // of type `MyContext`.
  const session = await conversation.external((ctx) => ctx.session);
}
```

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

### Interactive prompt: initialize git

Source: https://grammy.dev/hosting/cloudflare-workers-nodejs

Output of the create-cloudflare CLI after project creation, asking whether to use git for version control, with Yes/No highlighted.

```text
using create-cloudflare version 2.17.1

╭ Create an application with Cloudflare Step 1 of 3
│
├ In which directory do you want to create your application?
│ dir ./grammybot
│
├ What type of application do you want to create?
│ type "Hello World" Worker
│
├ Do you want to use TypeScript?
│ yes typescript
│
├ Copying template files
│ files copied to project directory
│
├ Updating name in `package.json`
│ updated `package.json`
│
├ Installing dependencies
│ installed via `npm install`
│
╰ Application created

╭ Configuring your application for Cloudflare Step 2 of 3
│
├ Installing @cloudflare/workers-types
│ installed via npm
│
├ Adding latest types to `tsconfig.json`
│ added @cloudflare/workers-types/2023-07-01
│
├ Retrieving current workerd compatibility date
│ compatibility date 2024-04-05
│
╰ Do you want to use git for version control?  // [!code focus]
 Yes / No  // [!code focus]
```

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

### Set up a new TypeScript project and install grammY with pnpm

Source: https://grammy.dev/guide/getting-started

Creates a new directory, initializes TypeScript, and installs grammY using pnpm. Run these commands in a terminal.

```sh
# Create a new directory and change into it.
mkdir my-bot
cd my-bot

# Set up TypeScript (skip if you use JavaScript).
pnpm add -D typescript
pnpm exec tsc --init

# Install grammY.
pnpm add grammy
```

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

### Webhook setup success response

Source: https://grammy.dev/hosting/cloudflare-workers

Example JSON response from Telegram when the webhook is set successfully.

```JSON
{
  "ok": true,
  "result": true,
  "description": "Webhook was set"
}
```

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

### Upload a file from disk (Deno)

Source: https://grammy.dev/guide/files

Shows how to create InputFile instances from a local file path or a Deno.FsFile instance in Deno.

```TypeScript
// Send a local file.
new InputFile("/path/to/file");

// Send a `Deno.FsFile` instance.
new InputFile(await Deno.open("/path/to/file"));
```

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

### Enter conversation on start command

Source: https://grammy.dev/ref/conversations/conversationcontrols

Example of entering a conversation called 'convo' when the /start command is received.

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

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

### Full example bot with freeStorage (JavaScript)

Source: https://grammy.dev/plugins/session

JavaScript version of the full example bot using persistent session data with the free storage adapter.

```JavaScript
const { Bot, session } = require("grammy");
const { freeStorage } = require("@grammyjs/storage-free");

// Create the bot and register the session middleware.
const bot = new Bot("");

bot.use(
  session({
    initial: () => ({ count: 0 }),
    storage: freeStorage(bot.token),
  }),
);

// Use persistent session data in update handlers.
bot.on("message", async (ctx) => {
  ctx.session.count++;
  await ctx.reply(`Message count: ${ctx.session.count}`);
});

bot.catch((err) => console.error(err));
bot.start();
```

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

### Install hydrate plugin inside a conversation (JavaScript)

Source: https://grammy.dev/plugins/conversations

JavaScript version of the same example, without type annotations. The hydrate plugin is installed on the conversation's context object via createConversation's plugins option.

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

async function convo(conversation, ctx) {
  // The hydrate plugin is installed on `ctx` here.
  const other = await conversation.wait();
  // The hydrate plugin is installed on `other` here, too.
}
bot.use(createConversation(convo, { plugins: [hydrate()] }));

bot.command("enter", async (ctx) => {
  // The hydrate plugin is NOT installed on `ctx` here.
  await ctx.conversation.enter("convo");
});
```

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

### Interactive prompt: deploy now?

Source: https://grammy.dev/hosting/cloudflare-workers-nodejs

Output of the create-cloudflare CLI after git initialization, asking whether to deploy the application, with Yes/No highlighted.

```text
using create-cloudflare version 2.17.1

╭ Create an application with Cloudflare Step 1 of 3
│
├ In which directory do you want to create your application?
│ dir ./grammybot
│
├ What type of application do you want to create?
│ type "Hello World" Worker
│
├ Do you want to use TypeScript?
│ yes typescript
│
├ Copying template files
│ files copied to project directory
│
├ Updating name in `package.json`
│ updated `package.json`
│
├ Installing dependencies
│ installed via `npm install`
│
╰ Application created

╭ Configuring your application for Cloudflare Step 2 of 3
│
├ Installing @cloudflare/workers-types
│ installed via npm
│
├ Adding latest types to `tsconfig.json`
│ added @cloudflare/workers-types/2023-07-01
│
├ Retrieving current workerd compatibility date
│ compatibility date 2024-04-05
│
├ Do you want to use git for version control?
│ yes git
│
├ Initializing git repo
│ initialized git
│
├ Committing new files
│ git commit
│
╰ Application configured

╭ Deploy with Cloudflare Step 3 of 3
│
╰ Do you want to deploy your application?  // [!code focus]
 Yes / No  // [!code focus]
```

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

### English translation file locales/en.ftl

Source: https://grammy.dev/plugins/i18n

Example Fluent translation file for English. Defines the 'start' and 'help' messages.

```ftl
start = Hi, how can I /help you?
help =
    Send me some text, and I can make it bold for you.
    You can change my language using the /language command.
```

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

### Install hydrate plugin inside a conversation (TypeScript)

Source: https://grammy.dev/plugins/conversations

TypeScript example showing how to install the hydrate plugin inside a conversation by passing it to createConversation's plugins option. The context types are defined separately for outside and inside contexts.

```TypeScript
// Only install the conversations plugin outside.
type MyContext = ConversationFlavor<Context>;
// Only install the hydrate plugin inside.
type MyConversationContext = HydrateFlavor<Context>;

bot.use(conversations());

// Pass the outside and the inside context object.
type MyConversation = Conversation<MyContext, MyConversationContext>;
async function convo(conversation: MyConversation, ctx: MyConversationContext) {
  // The hydrate plugin is installed on the parameter `ctx` here.
  const other = await conversation.wait();
  // The hydrate plugin is installed on the variable `other` here, too.
}
bot.use(createConversation(convo, { plugins: [hydrate()] }));

bot.command("enter", async (ctx) => {
  // The hydrate plugin is NOT installed on `ctx` here.
  await ctx.conversation.enter("convo");
});
```

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

### Set up a new TypeScript project and install grammY with yarn

Source: https://grammy.dev/guide/getting-started

Creates a new directory, initializes TypeScript, and installs grammY using yarn. Run these commands in a terminal.

```sh
# Create a new directory and change into it.
mkdir my-bot
cd my-bot

# Set up TypeScript (skip if you use JavaScript).
yarn add typescript -D
npx tsc --init

# Install grammY.
yarn add grammy
```

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

### Using ctx.t in bot commands

Source: https://grammy.dev/plugins/i18n

Example bot code that uses ctx.t to reply with the localized message for the 'start' and 'help' commands.

```ts
bot.command("start", async (ctx) => {
  await ctx.reply(ctx.t("start"));
});

bot.command("help", async (ctx) => {
  await ctx.reply(ctx.t("help"));
});
```

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

### German translation file locales/de.ftl

Source: https://grammy.dev/plugins/i18n

Example Fluent translation file for German. Provides the German equivalents for the 'start' and 'help' messages.

```ftl
start = Hallo, wie kann ich dir helfen? /help
help =
    Schick eine Textnachricht, die ich für dich fett schreiben soll.
    Du kannst mit dem Befehl /language die Spache ändern.
```

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

### Full example bot with freeStorage (Deno)

Source: https://grammy.dev/plugins/session

Deno version of the full example bot using persistent session data with the free storage adapter, importing from npm packages.

```TypeScript
import { Bot, Context, session, SessionFlavor } from "npm:grammy";
import { freeStorage } from "npm:@grammyjs/storages/free/src";

// Define the session structure.
interface SessionData {
  count: number;
}
type MyContext = Context & SessionFlavor<SessionData>;

// Create the bot and register the session middleware.
const bot = new Bot<MyContext>("");

bot.use(
  session({
    initial: () => ({ count: 0 }),
    storage: freeStorage<SessionData>(bot.token),
  }),
);

// Use persistent session data in update handlers.
bot.on("message", async (ctx) => {
  ctx.session.count++;
  await ctx.reply(`Message count: ${ctx.session.count}`);
});

bot.catch((err) => console.error(err));
bot.start();
```

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

### Initialize Firebase emulators

Source: https://grammy.dev/hosting/firebase

Run this command to set up the Firebase emulator suite. Select the functions emulator when prompted.

```Shell
firebase init emulators
```
Tokens:
Raw