grammY Telegram Bot Framework

To create a basic Telegram bot using grammY, follow these steps:

1. Obtain a Bot Token: Message @BotFather on Telegram to create a new bot and receive your API token.
2. Install grammY: Use npm to install the package in your project directory.
3. Initialize the Bot: Create a script (e.g., bot.js) using the Bot class.
4. Register Listeners: Use .on() to handle specific updates, such as message:text.
5. Start the Bot: Call .start() to begin long polling for updates.

Note: This example uses Node.js. For Deno, import from https://deno.land/x/grammy/mod.ts.

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

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

// Register listeners to handle messages
bot.on("message:text", (ctx) => ctx.reply("Echo: " + ctx.message.text));

// Start the bot (using long polling)
bot.start();

If you are using the Deno runtime, you can run your bot script by granting network permissions using the --allow-net flag.

deno run --allow-net bot.ts

grammY runs natively on Deno. To use grammY in a Deno project, import it from the following URL:

https://deno.land/x/grammy/mod.ts

To install the core grammY package for use in a Node.js project, run the following command in your project directory:

npm install grammy

If you are running your bot in a browser-compatible environment like Cloudflare Workers, you can use the web bundle included in the npm package. This allows you to import the Bot class directly from the grammy/web entry point.

import { Bot } from "grammy/web";

When your bot receives an update from Telegram, grammY wraps it in a Context object (commonly named ctx). This object is passed to all registered middleware and provides two primary capabilities:

1. Access to the Update: ctx.update holds the raw update object. The context provides numerous shortcuts to access specific parts of the update (e.g., ctx.message, ctx.callbackQuery) regardless of whether it's a new message, an edited message, or a channel post.
2. Access to the Bot API: ctx.api allows you to call any method of the Telegram Bot API directly. Additionally, the context provides high-level shortcuts for common actions, such as ctx.reply, which is a wrapper for ctx.api.sendMessage with the chat_id pre-filled.

Context objects can also be used to store state (like sessions) or match information (like ctx.match for regular expression captures).

Middleware is a function (or a container for a function) that acts as a listener for updates. When an update occurs, grammY passes a context object (ctx) to the middleware. The context object contains information about the update (like ctx.message) and provides shortcuts like ctx.reply() to interact with the user without manually specifying chat IDs.

To allow other middleware to run after the current one finishes its logic, you must call and await the next function provided as the second argument.

bot.on('message', ctx => ctx.reply('I got your message!'))
//                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
//                ^
//                |
//               This is middleware!

The Context.has object provides utility functions to generate predicate functions for probing context objects. These predicates can be used to check if a context meets specific conditions.

Calling a method directly on the context object (e.g., ctx.hasText(...)) is equivalent to using the predicate generated by Context.has (e.g., Context.has.text(...)(ctx)).

// Using the predicate generator
const hasText = Context.has.filterQuery(":text");
if (hasText(ctx)) { /* ... */ }

// Using the shorthand on the context object (equivalent)
if (ctx.has(":text")) { /* ... */ }

To prevent unauthorized requests from reaching your bot, you can use the secretToken option. When configured, grammY performs a constant-time comparison between the provided secretToken and the value of the X-Telegram-Bot-Api-Secret-Token header sent by Telegram. This protects your bot against timing attacks.

If the tokens do not match, the request is treated as unauthorized and the bot will not process the update.

If your bot runs on webhooks, you can use the canUseWebhookReply option and provide a WebhookReplyEnvelope. This allows grammY to perform up to one API call by including the result in the HTTP response of the webhook itself, saving an extra outgoing HTTP request.

Important Limitations:

1. You cannot handle errors for these calls (e.g., rate limits).
2. You won't have access to the full response object (e.g., the returned Message object).
3. Requests cannot be cancelled via AbortSignal.
4. It only works if the payload can be sent as JSON.

interface WebhookReplyEnvelope {
    send?: (payload: string) => void | Promise<void>;
}

// Example usage in configuration
const options = {
    canUseWebhookReply: (method) => method === 'sendMessage',
    // ...
};

A Transformer is a function that intercepts an API call. It receives the previous API call function (prev), the method name, the payload, and an AbortSignal. It must return a Promise that resolves to an ApiResponse.

Transformers are executed in the order they are registered via .use(). This pattern allows you to build complex logic like rate limiting, custom retries, or telemetry on top of the raw Telegram API calls.

type Transformer<R extends RawApi> = <M extends Methods<R>>(
    prev: ApiCallFn<R>,
    method: M,
    payload: Payload<M, R>,
    signal?: AbortSignal,
) => Promise<ApiResponse<ApiCallResult<M, R>>>;