+1
Daily
9,215
stars
1,650
forks
154
watchers
341
prs
1,004
issues
27
releases
README
✨ A Modern Telegram Bot API Library ✨
v2 is a from-scratch redesign, no v1 compatibility. Coming from v1? See the v1 - v2 migration guide in the changelog.
📦 Install
sh
npm install node-telegram-bot-api
Runs on Bun, modern Node.js, Deno, Cloudflare Workers and Vercel Functions λ
🚀 Usage
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()
📡 Calling the API directly
Api mirrors the wire API 1:1 - one method per Bot API method, each taking a single params object.
ts
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" });
// the same client is also on bot.api and ctx.api
🧩 Middleware
koa-style middleware around every update; on/command/hears are filters in the same chain. Wrap downstream work with await next().
ts
// ⏱️ time every update - and catch anything thrown downstream
bot.use(async (ctx, next) = {
const start = Date.now();
try {
await next();
} finally {
console.log(update took ${Date.now() - start}ms);
}
});
// 🧯 last-resort error handler
bot.catch((err, ctx) = console.error("handler failed", err));
⌨️ Keyboards & formatting
Structured fields are plain typed objects - pass a literal or use a fluent builder; the pipeline serializes either.
ts
import { Bot, InlineKeyboardBuilder, ReplyKeyboardBuilder, EntityBuilder } from "node-telegram-bot-api";
const bot = new Bot(process.env.BOT_TOKEN!);
// 🎛️ inline keyboard as reply_markup
await bot.api.sendMessage({
chat_id,
text: "Choose:",
reply_markup: new InlineKeyboardBuilder()
.text("A", "a")
.url("Docs", "https://core.telegram.org/bots/api")
.row()
.text("B", "b")
.build(),
});
// ⌨️ reply keyboard as reply_markup
await bot.api.sendMessage({
chat_id,
text: "Yes or no?",
reply_markup: new ReplyKeyboardBuilder()
.text("Yes")
.text("No")
.build({ resize_keyboard: true }),
});
// ✍️ rich text - EntityBuilder computes UTF-16 offsets for you
const { text, entities } = new EntityBuilder()
.plain("Hello ")
.bold("world")
.link("docs", "https://github.com/yagop/node-telegram-bot-aDiscussions
#1316Latest v1.0.0 release0 comments · 2026-06-14#1275Business Connection1 comments · 2025-08-09#1254send_chat_action support?0 comments · 2025-01-27#1246Bot API 7.11!!🙏🙏🙏0 comments · 2025-01-02#1238we need support Bot API 7.11!!1 comments · 2024-11-13#1235issue0 comments · 2024-11-01#1230how to implement deep linking ?0 comments · 2024-10-15#1221Payment Telegram Stars1 comments · 2024-08-12
Latest release
2.4.0 v2.4.0 2026-11-09Bot API 10.4 (November 9, 2026) Widgets - Added sendWidget, sendSharedWidget, answerWidgetQuery, editMessageWidgetData, and editSharedWidgetData. - Added Widget and widget on Message and ExternalReplyInfo. - Added WidgetQuery/SharedWidgetQuery and the widget_query/shared_widget_query update types, plus WidgetQueryType (WidgetQueryTypeData, WidgetQueryTypeSignData, WidgetQueryTypeSentTransaction) and WidgetQueryWallet. - Added InputWidgetMessageContent and InputSharedWidgetMessageContent. - ctx.chat/ctx.from resolve for widget queries (shared_widget_query has no chat). ts await bot.api.send