node-telegram-bot-api is a Telegram Bot API library for Node.js that runs on Bun, modern Node.js, Deno, Cloudflare Workers, and Vercel Functions.
The library solves the problem of building Telegram bots by providing a complete wrapper around the Telegram Bot API. It mirrors the wire API one-to-one with a single params object per method, while layering optional abstractions on top. The core approach uses koa-style middleware around every update, with filters like `on`, `command`, and `hears` integrated into the same chain. Keyboards and formatting use plain typed objects that can be passed as literals or built with a fluent builder. File uploads stream bytes directly from their source into requests, keeping memory flat regardless of file size; the tool handles retries for `Blob` and `Uint8Array` uploads but treats `ReadableStream` as one-shot to surface failures immediately.
Developers should choose this tool if they need to build Telegram bots for serverless environments or traditional Node servers. The webhook implementation uses web-standard callbacks as pure `(Request) => Promise<Response>` functions, making it compatible with Cloudflare Workers, Bun.serve, Deno Deploy, Vercel Edge, Next.js App Router, Express, and self-hosted Node servers. The library includes opt-in session middleware for persistent per-chat state, with an explicit store requirement so durability choices are never implicit. This design means the same code works under both one-invocation-per-update serverless and long-polling architectures. The v2 redesign is a from-scratch rewrite with no backward compatibility to v1.
The project maintains active development with regular updates and refinements to its API surface. The codebase is written in TypeScript, providing type safety throughout. The tool demonstrates attention to production concerns like webhook authentication via secret tokens and explicit session management patterns that avoid hidden state.
