node-telegram-bot-api

The library provides specialized helpers for different environments to handle Telegram webhooks. Use webhookCallback for Edge/Serverless (Cloudflare, Bun, Deno, Vercel), nextAppWebhook for Next.js App Router, registerExpressWebhook for Express, and startWebhook or createWebhookServer for Node.js servers.

// Cloudflare Workers / Bun.serve / Deno Deploy / Vercel Edge
import { Bot, webhookCallback } from "node-telegram-bot-api";
const bot = new Bot(TOKEN);
export default {
  fetch: webhookCallback(bot, { secretToken: SECRET }),
};

// Next.js App Router
import { Bot, nextAppWebhook } from "node-telegram-bot-api";
const bot = new Bot(process.env.BOT_TOKEN!);
export const POST = nextAppWebhook(bot, { secretToken: process.env.SECRET });

// Express
import express from "express";
import { Bot, registerExpressWebhook } from "node-telegram-bot-api";
const app = express();
const bot = new Bot(TOKEN);
registerExpressWebhook(bot, app, { path: "/telegram", secretToken: SECRET });

// Self-hosted Node server
import { Bot } from "node-telegram-bot-api";
import { createWebhookServer, startWebhook } from "node-telegram-bot-api/node";
const server = createWebhookServer(new Bot(TOKEN), { path: "/telegram", secretToken: SECRET });
server.listen(8080);

To upload files, use InputFile to wrap raw bytes, Blob, or Uint8Array. For Node.js environments, you can use fromPath to upload directly from disk. For replayable streaming uploads (to support retries), pass a factory function to InputFile that returns a fresh stream.

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" }) });

// 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" }),
});

// 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(),
});

Initialize a Bot instance with your token. You can register handlers for commands, regex patterns, and specific update types (like message or callback_query). Registration order determines priority. Use run(bot) from node-telegram-bot-api/node for a managed runner that handles graceful shutdowns (Ctrl-C).

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()