Node Telegram Bot API

https://github.com/yagop/node-telegram-bot-api
Admin
A Node.js module to interact with the official Telegram Bot API, enabling developers to create and...
Tokens:152,884
Snippets:1,063
Trust Score:9.1
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Initialize and run a Telegram bot

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/README.md

Example showing how to initialize a bot, register command and message handlers, and start the bot using the managed runner.

```ts
import { Bot, InlineKeyboardBuilder } from "node-telegram-bot-api";
import { run } from "node-telegram-bot-api/node"; // managed runner: wires Ctrl-C to bot.stop()

const bot = new Bot(process.env.BOT_TOKEN!);

// commands, regex and update types are all middleware - registration order wins
bot.command("start", (ctx) => ctx.reply("Hi! Send me anything."));
bot.hears(/echo (.+)/, (ctx) => ctx.reply(ctx.match![1]!));

bot.on("message", (ctx) =>
  ctx.reply("Pick one:", {
    reply_markup: new InlineKeyboardBuilder()
      .text("👍", "up")
      .text("👎", "down")
      .build(),
  }),
);

// 🔘 a tapped inline button comes back as a callback_query
bot.on("callback_query", async (ctx) => {
  await ctx.answerCallbackQuery({ text: `You tapped ${ctx.callbackQuery!.data}` });
});

await run(bot); // core-only alternative that runs anywhere: await bot.startPolling()
```

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

### Using getSession with middleware

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/context.md

Example of installing session middleware and accessing session data within a command handler. Throws an error if the session middleware is not installed or no key is present.

```ts
bot.use(createSession<{ count: number }>({ store: new MemorySessionStorage() }));
bot.command("count", (ctx) => {
  const s = ctx.getSession<{ count: number }>();
  s.data.count += 1;
  return ctx.reply(`Seen ${s.data.count} times`);
});
```

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

### Install dependencies with Bun

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/CLAUDE.md

Use bun install to install dependencies. CI uses --frozen-lockfile for reproducible installs.

```sh
bun install                       # install deps (CI uses --frozen-lockfile)
```

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

### Build and run examples with Bun

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/examples/README.md

Build the project to generate the dist directory, then execute an example bot using the BOT_TOKEN environment variable.

```sh
bun run build           # emits dist/ that the package "exports" map points at
BOT_TOKEN=... bun examples/01-polling-bot.ts
```

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

### createWebhookServer(bot, options?)

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/node.md

Creates (but does not start) a node:http server that handles webhook requests. Requests whose path differs from options.path (default '/') get 404; matching requests delegate to the core (req, res) handler.

```APIDOC
## createWebhookServer(bot, options?)

### Description
Creates (but does not start) a node:http server. Requests whose path differs from options.path (default '/') get 404; matching requests delegate to the core (req, res) handler (nodeFrameworkWebhook). The server is returned without .listen() — the caller picks the port.

### Method
function

### Signature
createWebhookServer(bot: Bot, options?: WebhookServerOptions): http.Server

### Parameters
#### Options (WebhookServerOptions)
- **path** (string) - Optional - Default: '/' - Only requests to this path are handled; others get 404.
- **All WebhookOptions** - Optional - Inherited from WebhookOptions.

### Usage Example
```ts
const server = createWebhookServer(bot, { path: "/telegram", secretToken: SECRET });
server.listen(8443);
```

### Returns
- **http.Server** - The created server (not started).
```

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

### Bot instantiation and getMe example

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/bot.md

Example of creating a Bot instance with options and calling getMe. Demonstrates error handling for construction or first call failures.

```typescript
import { Bot } from "node-telegram-bot-api";

const bot = new Bot(process.env.BOT_TOKEN!, {
  maxRetries: 2,
  rateLimit: { global: 20, perChat: 1 },
});

try {
  const me = await bot.api.getMe();
  console.log("Authorized as", me.username);
} catch (err) {
  console.error("construction or first call failed", err);
}
```

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

### init usage example

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/bot.md

Example of calling bot.init() to initialize middleware. It fails fast if a plugin's init fails, such as a bad session store.

```typescript
await bot.init(); // fail fast on a bad session store / plugin
```

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

### Examples

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/webhook.md

Usage examples for webhookCallback in various serverless environments.

```APIDOC
## Examples

### Workers / Bun.serve / Deno Deploy / Vercel Edge

```ts
import { Bot, webhookCallback } from "node-telegram-bot-api";

const bot = new Bot(process.env.BOT_TOKEN!);
bot.on("message", (ctx) => ctx.reply("hi from the edge"));

export default {
  fetch: webhookCallback(bot, { secretToken: process.env.WEBHOOK_SECRET! }),
};
```

### Early-ACK with a platform keep-alive

```ts
export default {
  fetch: (req: Request, _env: unknown, ctx: { waitUntil(p: Promise<unknown>): void }) =>
    webhookCallback(bot, {
      secretToken: SECRET,
      waitUntil: (p) => ctx.waitUntil(p),
    })(req),
};
```

### Error handling — the fail-loud opt-in makes Telegram redeliver

```ts
bot.catch((err) => {
  console.error("handler failed:", err);
  // default boundary: logs and consumes (no redelivery)
  // throw err; // -> webhookCallback responds 500 -> Telegram redelivers
});
```
```

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

### startWebhook(bot, options)

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/doc/api.md

Starts a managed webhook server using node:http, listening on the specified port and path. It handles graceful shutdown on SIGINT/SIGTERM and rejects if the server fails to start.

```APIDOC
## startWebhook(bot, options)

### Description
Managed webhook runner: create a `node:http` webhook server, start listening, and resolve when it shuts down. Once listening, installs `SIGINT`/`SIGTERM` handlers that close the server for a graceful exit (cleaned up in a `finally`), mirroring `run()` for long polling. Rejects if the server fails to start (e.g. the port is in use).

Shutdown cannot hang: `server.close()` waits for existing connections to end, so we also drop idle keep-alive sockets at once and force-close anything still busy past `shutdownTimeoutMs`.

You still register the webhook with Telegram yourself, pointing at this server's public URL (terminate TLS at a proxy/tunnel in front of it):
  api.setWebhook({ url, secret_token })

### Parameters
- `bot` (Bot) - Required - The bot instance.
- `options` (StartWebhookOptions) - Required - Options for the webhook server, including port and path.

### Returns
Promise<void>

### Example
```ts
await startWebhook(bot, { port: 8443, path: "/telegram", secretToken });
```
```

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

### startWebhook() with port, path, and secretToken

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/doc/api.md

Starts a managed webhook server that listens on the given port and path, and resolves when it shuts down. It installs SIGINT/SIGTERM handlers for graceful exit and rejects if the server fails to start (e.g., port in use). You must register the webhook with Telegram yourself, pointing at this server's public URL.

```typescript
await startWebhook(bot, { port: 8443, path: "/telegram", secretToken });
```

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

### Install node-telegram-bot-api

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/README.md

Use npm to install the library in your project.

```sh
npm install node-telegram-bot-api
```

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

### catch usage example

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/bot.md

Example of installing a custom error handler with bot.catch. The handler logs the error and can optionally rethrow to opt into fail-loud behavior.

```typescript
bot.catch((err, ctx) => {
  console.error(`update ${ctx.update.update_id} failed:`, err);
  // fail-loud opt-in:
  // throw err;
});
```

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

### command usage examples

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/bot.md

Examples of using the `command` method to handle `/start`, `/help`, and `/echo` commands. The `ctx.match` property contains the trimmed arguments string.

```typescript
bot.command("start", (ctx) => ctx.reply("Hi!"));
bot.command(["start", "help"], (ctx) => ctx.reply("Help text"));
bot.command("echo", (ctx) => ctx.reply(ctx.match || "(nothing to echo)"));
```

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

### createWebhookServer: Create and listen on webhook server

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/doc/api.md

Creates a webhook server for the bot with a custom path and secret token, then starts listening on port 8443. Requests with a different path get a 404.

```typescript
const server = createWebhookServer(bot, { path: "/telegram", secretToken });
server.listen(8443);
```

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

### Example usage of compose

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/compose.md

Shows how to import and use `compose` to create a middleware chain. The example increments `ctx.n` and logs after downstream.

```typescript
import { compose } from "node-telegram-bot-api";

const chain = compose<{ n: number }>([
  async (ctx, next) => {
    ctx.n += 1;
    await next(); // downstream
    console.log("after downstream");
  },
  (ctx) => {
    ctx.n += 10;
  },
]);

const ctx = { n: 0 };
await chain(ctx); // ctx.n === 11
```

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

### ReplyKeyboardBuilder usage example

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/keyboard.md

Example of creating a reply keyboard with specific build options and sending it via the sendMessage API.

```ts
const markup = new ReplyKeyboardBuilder()
  .text("Yes")
  .text("No")
  .build({ resize_keyboard: true });

await bot.api.sendMessage({ chat_id, text: "Yes or no?", reply_markup: markup });
```

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

### InlineKeyboardBuilder usage example

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/keyboard.md

Example of creating an inline keyboard with buttons and sending it via the sendMessage API.

```ts
import { InlineKeyboardBuilder, sendMessage } from "node-telegram-bot-api"; // sendMessage via api

const markup = new InlineKeyboardBuilder()
  .text("👍", "up")
  .text("👎", "down")
  .row()
  .url("Docs", "https://core.telegram.org/bots/api")
  .build();

await bot.api.sendMessage({ chat_id, text: "Pick one:", reply_markup: markup });
```

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

### Workers / Bun.serve / Deno Deploy / Vercel Edge example

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/webhook.md

Example of setting up a webhook callback for edge runtimes. It creates a bot, listens for messages, and exports a fetch handler using `webhookCallback` with a secret token.

```typescript
import { Bot, webhookCallback } from "node-telegram-bot-api";

const bot = new Bot(process.env.BOT_TOKEN!);
bot.on("message", (ctx) => ctx.reply("hi from the edge"));

export default {
  fetch: webhookCallback(bot, { secretToken: process.env.WEBHOOK_SECRET! }),
};
```

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

### Typecheck examples against source

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/examples/README.md

Use the TypeScript compiler with the provided examples configuration to validate imports against the source code without building.

```sh
./node_modules/.bin/tsc -p examples/tsconfig.json --noEmit
```

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

### InputFile Usage Examples

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/files.md

Examples of creating InputFile instances for sending documents, videos, and media groups, including raw bytes, replayable streaming uploads, and nested InputFile hoisting.

```APIDOC
## InputFile Usage Examples

### Description
Demonstrates how to use InputFile to send files as raw bytes, replayable streaming uploads, and nested InputFile in media groups.

### Usage

```ts
import { Bot, InputFile, MediaGroupBuilder } from "node-telegram-bot-api";
import { fromPath } from "node-telegram-bot-api/node";

// raw bytes (web-standard, runs anywhere)
await bot.api.sendDocument({
  chat_id,
  document: new InputFile(bytes, { filename: "report.pdf" }),
});

// replayable streaming upload: the factory opens a new stream per attempt
await bot.api.sendVideo({
  chat_id,
  video: new InputFile(() => openVideoStream(), { filename: "video.mp4", contentType: "video/mp4" }),
});

// nested InputFile hoisted to an attach:// part automatically
await bot.api.sendMediaGroup({
  chat_id,
  media: [
    { type: "photo", media: new InputFile(bytesA, { filename: "a.jpg" }), caption: "A" },
    { type: "photo", media: "https://telegram.org/example/photo.jpg" },
  ],
});
```

### Error Handling with One-Shot Stream

```ts
const oneShot = new InputFile(readableOnce, { filename: "x.bin" });
try {
  await api.sendDocument({ chat_id, document: oneShot });
} catch (err) {
  // the first failure surfaces immediately; the stream cannot be re-sent
}
```

```

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

### Transport usage example

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/transport.md

Shows how to instantiate Transport with a token and timeout, then call request to get the bot user. The request method handles retries and error classification.

```typescript
const transport = new Transport("123:abc", { timeoutMs: 10_000 });
const me = await transport.request<User>("getMe");
```

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

### RichMessageButtonBuilder usage example

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/richtext.md

Example of building a button with the builder, setting a danger style and callback data, then building the button.

```typescript
const button = new RichMessageButtonBuilder("Delete?")
  .style("danger")
  .callbackData("confirm")
  .build();
```

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

### WebhookServerOptions / StartWebhookOptions

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/configuration.md

Options for creating a webhook server or starting a webhook. Use with createWebhookServer or startWebhook.

```APIDOC
## WebhookServerOptions / StartWebhookOptions

### Description
Options for creating a webhook server or starting a webhook. Use with `createWebhookServer` or `startWebhook`. Includes all `WebhookOptions` plus the following.

### Properties
- **path** (string) - Optional, default `"/"` - Only this request path is handled; others get 404
- **port** (number) - Required for `startWebhook` - Port to listen on
- **hostname** (string) - Optional, default all interfaces - Interface to bind
- **shutdownTimeoutMs** (number) - Optional, default `10_000` - Force-close busy connections after this on shutdown

```

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

### getFile

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/doc/api.md

Gets basic information about a file and prepares it for downloading.

```APIDOC
## getFile

### Description
Gets basic information about a file and prepares it for downloading.

### Method
GET

### Endpoint
https://api.telegram.org/bot<token>/getFile

### Parameters
#### Path Parameters
- **token** (string) - Required - Bot authentication token.

#### Query Parameters
- **file_id** (string) - Required - File identifier to get info about.

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates success.
- **result** (File) - The file object.

#### Response Example
{
  "ok": true,
  "result": {
    "file_id": "string",
    "file_unique_id": "string",
    "file_size": 0,
    "file_path": "string"
  }
}
```

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

### Initialize FileSessionStorage

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/node.md

Example of configuring the bot to use FileSessionStorage for session persistence.

```ts
import { createSession } from "node-telegram-bot-api";
import { FileSessionStorage } from "node-telegram-bot-api/node";

bot.use(createSession({ store: new FileSessionStorage({ path: "./.sessions" }) }));
await bot.init(); // bad path fails here
```

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

### Bot startPolling usage

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/longpoll.md

Example showing how startPolling uses longPoll as its default update source.

```ts
await bot.startPolling(); // equivalent to longPoll(api, {}, signal)
```

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

### getMyShortDescription

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/api.md

Gets the bot's short description. Returns a BotShortDescription object.

```APIDOC
## getMyShortDescription

### Description
Gets the bot's short description.

### Method
getMyShortDescription

### Parameters
- **GetMyShortDescriptionParams** - Optional - Parameters for the operation.

### Returns
- **BotShortDescription** - Bot short description information.
```

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

### Using RedisSessionStorage with bot middleware

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/bun.md

Example of configuring the session middleware with a custom Redis prefix.

```ts
bot.use(createSession({
  store: new RedisSessionStorage({ prefix: "great_bot:sessions:" }),
  ttlSeconds: 86400,
}));
```

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

### reply with force_reply

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/context.md

Example of using reply to prompt a user for input with a force_reply markup.

```ts
bot.command("start", (ctx) =>
  ctx.reply("Tell me your name?", { reply_markup: { force_reply: true } })
);
```

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

### Configure FileSessionStorage for Node

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/README.md

Example of using FileSessionStorage for durable session persistence on a Node.js host.

```ts
// durable on Node (e.g. a webhook on one host)
import { createSession } from "node-telegram-bot-api";
import { FileSessionStorage } from "node-telegram-bot-api/node";
bot.use(createSession<Session>({ store: new FileSessionStorage({ path: "./.great_bot_sessions" }) }));
```

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

### startPolling usage example

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/bot.md

Example of starting polling with a timeout of 30 seconds, then stopping it later and awaiting the run promise. The runPromise resolves once the pump is stopped.

```typescript
await bot.startPolling({ timeout: 30 });
// later:
bot.stop();
await runPromise; // resolves once stopped
```

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

### Create and listen with a webhook server

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/node.md

Demonstrates creating a webhook server instance and manually starting it on a specific port.

```ts
const server = createWebhookServer(bot, { path: "/telegram", secretToken: SECRET });
server.listen(8443);
```

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

### init()

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/bot.md

Runs every registered middleware's init() once, in registration order. Memoized; a failure is not cached, so the next call retries and resumes at the plugin that failed.

```APIDOC
## init()

### Description
Runs every registered middleware's init() once, in registration order. Memoized (a failure is not cached — the next call retries and resumes at the plugin that failed). Awaited by startPolling() and handleUpdate().

### Method
init

### Signature
init(): Promise<void>

### Returns
Promise<void>

### Example
```ts
await bot.init(); // fail fast on a bad session store / plugin
```
```

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

### Api usage example

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/api.md

Imports Api, creates an instance with a token from environment, and calls getMe and sendMessage. The same client is available as bot.api and ctx.api.

```typescript
import { Api } from "node-telegram-bot-api";

const api = new Api(process.env.BOT_TOKEN!);
const me = await api.getMe();
await api.sendMessage({ chat_id: 12345, text: "hello" });
```

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

### Define StartWebhookOptions and startWebhook function

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/node.md

Defines the configuration for starting a webhook server and the signature of the startWebhook function.

```ts
export interface StartWebhookOptions extends WebhookServerOptions {
  /** Port to listen on. */
  port: number;
  /** Hostname / interface to bind. Default: all interfaces. */
  hostname?: string;
  /** Grace period before in-flight connections are force-closed on shutdown, in ms. Default 10000. */
  shutdownTimeoutMs?: number;
}

export async function startWebhook(bot: Bot, options: StartWebhookOptions): Promise<void>
```

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

### handleUpdate usage example

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/bot.md

Example of calling handleUpdate with a sample update object. The update object contains an update_id and a message.

```typescript
await bot.handleUpdate({ update_id: 1, message: { /* … */ } });
```

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

### Initialize Session Middleware

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/README.md

Demonstrates using bot.init() to trigger session store setup at startup, ensuring errors are caught early.

```ts
bot.use(createSession<Session>({ store: new FileSessionStorage({ path: "./.great_bot_sessions" }) }));
await bot.init(); // optional: a bad path / unreachable backend fails here, at boot
```

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

### Configure SQL and SQLite Session Storage for Bun

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/README.md

Example of using SQL and SQLite storage backends on Bun for session persistence.

```ts
// SQL alternatives on Bun: a separate table or database file for this bot
import { SqlSessionStorage, SqliteSessionStorage } from "node-telegram-bot-api/bun";
const sqlStore = new SqlSessionStorage({ table: "great_bot_sessions" });
const sqliteStore = new SqliteSessionStorage({ database: "./great_bot_sessions.db" });
```

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

### Start a managed webhook server

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/node.md

Starts the webhook server using the managed runner, which handles lifecycle events like SIGINT/SIGTERM.

```ts
await startWebhook(bot, { port: 8443, path: "/telegram", secretToken: SECRET });
```

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

### close usage example

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/bot.md

Example of calling bot.close() with error handling. The catch block logs any error, which may be an AggregateError if multiple plugins failed.

```typescript
try {
  await bot.close();
} catch (err) {
  console.error("close failed (possibly AggregateError)", err);
}
```

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

### startWebhook(bot, options)

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/node.md

Managed runner that listens first (rejects on early error, e.g. port in use), then wires SIGINT/SIGTERM to graceful close. Shutdown cannot hang: gracefulClose stops accepting, drops idle keep-alive sockets at once, and force-closes anything still busy past the timeout.

```APIDOC
## startWebhook(bot, options)

### Description
Managed runner that listens first (rejects on an early error, e.g. port in use), then wires SIGINT/SIGTERM to graceful close. Shutdown cannot hang: gracefulClose(server, timeoutMs) stops accepting, drops idle keep-alive sockets at once, and force-closes anything still busy past the timeout. You still register the webhook with Telegram yourself (api.setWebhook({ url, secret_token })) pointing at this server's public URL (terminate TLS at a proxy/tunnel in front of it).

### Method
async function

### Signature
startWebhook(bot: Bot, options: StartWebhookOptions): Promise<void>

### Parameters
#### Options (StartWebhookOptions)
- **port** (number) - Required - Port to listen on.
- **hostname** (string) - Optional - Default: all interfaces - Hostname / interface to bind.
- **shutdownTimeoutMs** (number) - Optional - Default: 10000 - Grace period before in-flight connections are force-closed on shutdown, in ms.
- **path** (string) - Optional - Default: '/' - Only requests to this path are handled; others get 404.
- **All WebhookOptions** - Optional - Inherited from WebhookOptions.

### Usage Example
```ts
await startWebhook(bot, { port: 8443, path: "/telegram", secretToken: SECRET });
```

### Behavior
- Listens first; rejects on early error (e.g. port in use).
- Wires SIGINT/SIGTERM to graceful close.
- Shutdown cannot hang: gracefulClose stops accepting, drops idle keep-alive sockets at once, and force-closes anything still busy past the timeout.
```

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

### hears usage examples

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/bot.md

Examples of using the `hears` method to match exact strings and regular expressions. The `ctx.match` property contains the matched text or RegExpMatchArray.

```typescript
bot.hears("ping", (ctx) => ctx.reply("pong"));
bot.hears(/^roll (\d+)$/, (ctx) => {
  const sides = Number(ctx.match![1]);
  return ctx.reply(`🎲 ${1 + Math.floor(Math.random() * sides)}`);
});
```

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

### init()

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/bun.md

Initializes the storage by creating the sessions table if it does not exist. The initialization is lazy and memoized; it is cleared on failure so a retry re-attempts.

```APIDOC
## `init()`

### Description
Runs `CREATE TABLE IF NOT EXISTS` to ensure the sessions table exists. The operation is memoized and cleared on failure, allowing retries. It is run at boot by `bot.init()`.

### Method
`init(): Promise<void>`

### Parameters
None.

### Returns
`Promise<void>` - Resolves when the table is ready.
```

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

### Uploading files and media groups

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/README.md

Demonstrates uploading from disk, raw bytes, and using MediaGroupBuilder for structured media collections.

```ts
import { Bot, InputFile, MediaGroupBuilder } from "node-telegram-bot-api";
import { fromPath } from "node-telegram-bot-api/node";

const bot = new Bot(process.env.BOT_TOKEN!);

// upload from disk (Node only)
await bot.api.sendPhoto({ chat_id, photo: await fromPath("./cat.jpg") });
// upload raw bytes (web-standard, runs anywhere)
await bot.api.sendDocument({ chat_id, document: new InputFile(bytes, { filename: "report.pdf" }) });

// a raw InputFile nested in a structure is auto-hoisted to an attach:// part
await bot.api.sendMediaGroup({
  chat_id,
  media: [
    { type: "photo", media: new InputFile(bytesA, { filename: "a.jpg" }), caption: "A" },
    { type: "photo", media: "https://telegram.org/example/photo.jpg" },
  ],
});

// MediaGroupBuilder: optional sugar for the same array
await bot.api.sendMediaGroup({
  chat_id,
  media: new MediaGroupBuilder()
    .photo({ media: new InputFile(bytesA, { filename: "a.jpg" }), caption: "A" })
    .photo({ media: "https://telegram.org/example/photo.jpg" })
    .build(),
});
```

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

### String-tag reply tracking example

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/reply-tracking.md

Example using taggedReplies with string tags. It expects a reply with a tag and matches it, returning the tag or undefined. The Tag union type is used to ensure consistency.

```typescript
bot.command("start", async (ctx) => {
  const sent = await ctx.reply("What's your name?", { reply_markup: { force_reply: true } });
  taggedReplies<"name" | "email">(ctx).expect(sent.message_id, "name");
});

bot.on("message", async (ctx, next) => {
  const step = taggedReplies<"name" | "email">(ctx).match(); // "name" | "email" | undefined
  if (!step) return next();
  // ...proceed for `step`
});
```

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

### Object-tag reply tracking example

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/reply-tracking.md

Example using expectReply and matchReply with object tags. It sets up a session, expects a reply with a step tag, and matches it in a message handler. The ttlSeconds option is set to 3600.

```typescript
import { Bot, createSession, MemorySessionStorage, expectReply, matchReply, taggedReplies } from "node-telegram-bot-api";

bot.use(createSession({ store: new MemorySessionStorage() }));

bot.command("start", async (ctx) => {
  const sent = await ctx.reply("Your name?", { reply_markup: { force_reply: true } });
  expectReply(ctx, sent.message_id, { step: "name" }, { ttlSeconds: 3600 });
});

bot.on("message", async (ctx, next) => {
  const hit = matchReply<{ step: string }>(ctx);
  if (!hit) return next(); // not a reply we're waiting on
  await ctx.reply(`Answering step ${hit.step}`);
});
```

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

### getStickerSet

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/doc/api.md

Gets a sticker set.

```APIDOC
## getStickerSet

### Description
Gets a sticker set.

### Method
GET

### Endpoint
https://api.telegram.org/bot<token>/getStickerSet

### Parameters
#### Path Parameters
- **token** (string) - Required - Bot authentication token.

#### Query Parameters
- **name** (string) - Required - Name of the sticker set.

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates success.
- **result** (StickerSet) - The sticker set object.

#### Response Example
{
  "ok": true,
  "result": {
    "name": "string",
    "title": "string",
    "sticker_type": "regular",
    "stickers": []
  }
}
```

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

### Configure RedisSessionStorage for Bun

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/README.md

Example of using RedisSessionStorage on Bun, configured for cross-instance sharing with a TTL of one day.

```ts
// durable on Bun, shared across instances, idle sessions expiring after a day
import { RedisSessionStorage } from "node-telegram-bot-api/bun";
bot.use(createSession<Session>({
  store: new RedisSessionStorage({ prefix: "great_bot:sessions:" }),
  ttlSeconds: 86400,
}));
```

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

### constructor

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/transport.md

Creates a new Transport instance with the given bot token and optional transport options. Throws synchronously on invalid token or missing fetch implementation.

```APIDOC
## Constructor

### Description
Creates a new Transport instance with the given bot token and optional transport options.

### Signature
```ts
constructor(
  private readonly token: string,
  options: TransportOptions = {}
)
```

### Parameters
- **token** (string) - Required - The Telegram bot token.
- **options** (TransportOptions) - Optional - Transport configuration options.

### Throws
- `TelegramBotError` with `code: "EPARAM"` when `token` is falsy.
- `NetworkError` when `options.fetch` is missing and `globalThis.fetch` is not a function.
```

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

### getChatGifts

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/doc/api.md

Gets the gifts owned by a chat.

```APIDOC
## getChatGifts

### Description
Gets the gifts owned by a chat.

### Method
GET

### Endpoint
https://api.telegram.org/bot<token>/getChatGifts

### Parameters
#### Path Parameters
- **token** (string) - Required - Bot authentication token.

#### Query Parameters
- **chat_id** (integer or string) - Required - Unique identifier for the target chat.

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates success.
- **result** (OwnedGifts) - The owned gifts object.

#### Response Example
{
  "ok": true,
  "result": {
    "gifts": []
  }
}
```

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

### getBusinessAccountGifts

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/doc/api.md

Gets gifts for a business account.

```APIDOC
## getBusinessAccountGifts

### Description
Gets gifts for a business account.

### Method
POST

### Endpoint
getBusinessAccountGifts

### Parameters
#### Body Parameters
- **params** (GetBusinessAccountGiftsParams) - Required - The parameters for getting business account gifts.
- **signal** (AbortSignal) - Optional - An optional abort signal to cancel the request.

### Response
#### Success Response (200)
- **OwnedGifts** - The owned gifts.

```

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

### Using specialized builders for stickers, profile photos, and stories

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/README.md

Examples of using StickerSetBuilder, StaticProfilePhotoBuilder, and PhotoStoryBuilder to construct complex API requests.

```ts
import {
  Bot,
  InputFile,
  StickerSetBuilder,
  StaticProfilePhotoBuilder,
  PhotoStoryBuilder,
} from "node-telegram-bot-api";

const bot = new Bot(process.env.BOT_TOKEN!);

// collect a sticker set
await bot.api.createNewStickerSet({
  user_id,
  name,
  title,
  stickers: new StickerSetBuilder()
    .add({ sticker: new InputFile(pngBytes, { filename: "sticker.png" }), format: "static", emoji_list: ["🙂"] })
    .build(),
});

// a single sticker is a plain InputSticker - no builder needed
await bot.api.addStickerToSet({
  user_id,
  name,
  sticker: { sticker: new InputFile(pngBytes, { filename: "sticker.png" }), format: "static", emoji_list: ["🙂"] },
});

// profile photo: Static / AnimatedProfilePhotoBuilder
await bot.api.setMyProfilePhoto({
  photo: new StaticProfilePhotoBuilder({ photo: new InputFile(pngBytes, { filename: "avatar.png" }) }).build(),
});

// story: Photo / VideoStoryBuilder
await bot.api.postStory({
  business_connection_id,
  active_period,
  content: new PhotoStoryBuilder({ photo: new InputFile(pngBytes, { filename: "story.png" }) }).build(),
});
```

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

### getMyStarBalance

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/doc/api.md

Gets the bot's star balance.

```APIDOC
## getMyStarBalance

### Description
Gets the bot's star balance.

### Method
GET

### Endpoint
https://api.telegram.org/bot<token>/getMyStarBalance

### Parameters
#### Path Parameters
- **token** (string) - Required - Bot authentication token.

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates success.
- **result** (StarAmount) - The star amount object.

#### Response Example
{
  "ok": true,
  "result": {
    "amount": 100
  }
}
```

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

### getBusinessAccountStarBalance

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/doc/api.md

Gets the star balance of a business account.

```APIDOC
## getBusinessAccountStarBalance

### Description
Gets the star balance of a business account.

### Method
POST

### Endpoint
getBusinessAccountStarBalance

### Parameters
#### Body Parameters
- **params** (GetBusinessAccountStarBalanceParams) - Required - The parameters for getting the star balance.
- **signal** (AbortSignal) - Optional - An optional abort signal to cancel the request.

### Response
#### Success Response (200)
- **StarAmount** - The star balance.

```

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

### getMyDescription

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/doc/api.md

Gets the current default administrator rights of the bot.

```APIDOC
## getMyDescription

### Description
Gets the current default administrator rights of the bot.

### Method
GET

### Endpoint
https://api.telegram.org/bot<token>/getMyDescription

### Parameters
#### Path Parameters
- **token** (string) - Required - Bot authentication token.

#### Query Parameters
- **language_code** (string) - Optional - A two-letter ISO 639-1 language code.

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates success.
- **result** (BotDescription) - The bot description object.

#### Response Example
{
  "ok": true,
  "result": {
    "description": "string"
  }
}
```

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

### Sending files with InputFile

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/files.md

Demonstrates sending documents, streaming videos, and media groups using InputFile with raw bytes, factory functions, and automatic attachment handling.

```ts
import { Bot, InputFile, MediaGroupBuilder } from "node-telegram-bot-api";
import { fromPath } from "node-telegram-bot-api/node";

// raw bytes (web-standard, runs anywhere)
await bot.api.sendDocument({
  chat_id,
  document: new InputFile(bytes, { filename: "report.pdf" }),
});

// replayable streaming upload: the factory opens a new stream per attempt
await bot.api.sendVideo({
  chat_id,
  video: new InputFile(() => openVideoStream(), { filename: "video.mp4", contentType: "video/mp4" }),
});

// nested InputFile hoisted to an attach:// part automatically
await bot.api.sendMediaGroup({
  chat_id,
  media: [
    { type: "photo", media: new InputFile(bytesA, { filename: "a.jpg" }), caption: "A" },
    { type: "photo", media: "https://telegram.org/example/photo.jpg" },
  ],
});
```

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

### Session middleware error handling and session.find usage

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/session.md

Demonstrates using session.find to handle keyless updates without throwing, and shows the recommended pattern for initializing and closing the bot to fail fast on bad stores and release resources.

```typescript
const session = createSession<Session>({ store: new MemorySessionStorage() });
bot.use(session);
bot.use(async (ctx, next) => {
  const s = session.find(ctx); // undefined for polls, inline queries, ...
  if (s) s.data.count++;
  next();
});
await bot.init(); // fail fast on a bad store
// ...
await bot.close(); // releases store resources
```

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

### getCustomEmojiStickers

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/doc/api.md

Gets information about custom emoji stickers by their identifiers.

```APIDOC
## getCustomEmojiStickers

### Description
Gets information about custom emoji stickers by their identifiers.

### Method
GET

### Endpoint
https://api.telegram.org/bot<token>/getCustomEmojiStickers

### Parameters
#### Path Parameters
- **token** (string) - Required - Bot authentication token.

#### Query Parameters
- **custom_emoji_ids** (array of string) - Required - List of custom emoji identifiers.

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates success.
- **result** (array of Sticker) - The list of stickers.

#### Response Example
{
  "ok": true,
  "result": [
    {
      "file_id": "string",
      "type": "regular",
      "width": 512,
      "height": 512,
      "is_animated": false,
      "is_video": false
    }
  ]
}
```

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

### getAvailableGifts

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/api.md

Gets available gifts. Returns a Gifts object.

```APIDOC
## getAvailableGifts

### Description
Gets available gifts.

### Method
getAvailableGifts

### Parameters
None

### Returns
- **Gifts** - Available gifts.
```

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

### Importing Bun-specific session stores

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/bun.md

Import the core Bot/session from the main package and the specific store from the bun subpath.

```ts
import { createSession } from "node-telegram-bot-api";
import { RedisSessionStorage, SqlSessionStorage, SqliteSessionStorage } from "node-telegram-bot-api/bun";
```

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

### getBusinessConnection

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/api.md

Gets a business connection. Returns a BusinessConnection object.

```APIDOC
## getBusinessConnection

### Description
Gets a business connection.

### Method
getBusinessConnection

### Parameters
- **GetBusinessConnectionParams** - Required - Parameters for the operation.

### Returns
- **BusinessConnection** - Business connection information.
```

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

### Basic session middleware usage with MemorySessionStorage

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/session.md

Shows how to create a bot with session middleware using MemorySessionStorage, initialize a session, and increment a counter in a command handler.

```typescript
import { Bot, createSession, MemorySessionStorage } from "node-telegram-bot-api";

type Session = { count: number };

const bot = new Bot(process.env.BOT_TOKEN!);
bot.use(createSession<Session>({
  store: new MemorySessionStorage(),
  initial: () => ({ count: 0 }),
}));

bot.command("count", async (ctx) => {
  const s = ctx.getSession<Session>(); // or: session.get(ctx) with the middleware kept
  s.data.count++;
  await ctx.reply(`Seen ${s.data.count} times`);
});
```

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

### getChatMemberCount

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/api.md

Gets the number of members in a chat. Returns a number.

```APIDOC
## getChatMemberCount

### Description
Gets the number of members in a chat.

### Method
getChatMemberCount

### Parameters
- **GetChatMemberCountParams** - Required - Parameters for the operation.

### Returns
- **number** - Member count.
```

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

### Initialize SqliteSessionStorage with bot

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/bun.md

Example of integrating SqliteSessionStorage into a bot session middleware using a local database file.

```ts
bot.use(createSession({
  store: new SqliteSessionStorage({ database: "./great_bot_sessions.db" }),
}));
```

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

### getChat

Source: https://github.com/yagop/node-telegram-bot-api/blob/master/_autodocs/api-reference/api.md

Gets information about a chat. Returns a ChatFullInfo object.

```APIDOC
## getChat

### Description
Gets information about a chat.

### Method
getChat

### Parameters
- **GetChatParams** - Required - Parameters for the operation.

### Returns
- **ChatFullInfo** - Chat information.
```
Tokens:
Raw