Node.js Telegram Bot API Files

Rewritten in TypeScript

The library has been rewritten from JavaScript to TypeScript and now requires Node.js ≥ 18. The public surface — the TelegramBot class, its method names, their positional arguments, and the emitted events — is otherwise unchanged, so most bots keep working after the breaking changes below.

Migrating from v0.67.x

• ESM-only. The package is "type": "module"; require() no longer works — use import TelegramBot from "node-telegram-bot-api". The class is both the default and a named export. If you are stuck on CommonJS, load it with a dynamic import: const { default: TelegramBot } = await import("node-telegram-bot-api").
• answerCallbackQuery — the legacy answerCallbackQuery(id, text, showAlert) and answerCallbackQuery([options]) forms are removed; use answerCallbackQuery(id, { text, show_alert }).
• thumb → thumbnail on sendAudio / sendDocument / sendVideo / sendAnimation / sendVoice and the sticker methods.
• reply_to_message_id → reply_parameters: { reply_parameters: { message_id } }.
• Reply-keyboard string shorthand removed. KeyboardButton is an object only; use keyboard: [[{ text: "Yes" }]] instead of keyboard: [["Yes"]]. (reply_markup is still serialized for you, or you may pass a pre-stringified value.)
• Error response shape. Errors still expose code (EFATAL / EPARSE / ETELEGRAM) and response, but response is now a plain object, not the raw http.IncomingMessage: read error.response.status (was response.statusCode); error.response.body is unchanged.
• NTBA_FIX_350 removed. filename / contentType are always auto-resolved (including magic-byte sniffing of Buffers); override per call via the file-options argument.
• request constructor option still exists but feeds the internal fetch-based HttpClient (timeouts, default headers) rather than the old request library — review any proxy/agent configuration.
• Build output moved from lib/ to dist/.

Breaking changes for @types/node-telegram-bot-api users

The bundled types replace the community @types/node-telegram-bot-api (DefinitelyTyped) package. Uninstall @types/node-telegram-bot-api; the following differences affect existing typed code:

• Types are no longer namespaced. The old package exposed everything under a TelegramBot.* namespace (TelegramBot.Message, TelegramBot.ChatId, …). Types are now flat named exports — replace TelegramBot.Message with a named import: import TelegramBot, { type Message } from "node-telegram-bot-api". The default import of the class is unchanged.
• *Options interfaces are now *Params types. Per-method option interfaces (SendMessageOptions, SendPhotoOptions, …) are replaced by docs-faithful <Method>Params types that include the positional arguments; each method types its trailing argument as Omit<<Method>Params, …>. There are no aliases under the old names.
• Renamed types: ConstructorOptions → TelegramBotOptions, StartPollingOptions → PollingStartOptions, StopPollingOptions → PollingStopOptions, FileOptions → FileMeta, Metadata → EventMetadata, TelegramEvents → TelegramBotEvents. TextListener / ReplyListener are no longer exported.
• restrictChatMember(chatId, userId, permissions, options?) — permissions is now a required positional argument, not an option field.
• sendPoll — pollOptions changed from string[] to InputPollOption[] ({ text, … } objects), matching the current Bot API.
• setStickerSetThumb → setStickerSetThumbnail (method renamed; adds a format option).
• Removed legacy option fields (the generated params are docs-faithful): disable_web_page_preview (use link_preview_options), top-level allow_sending_without_reply (use reply_parameters), and answerInlineQuery's switch_pm_text / switch_pm_parameter (use button).
• Constructor request option is no longer the request library's Options type — the client is fetch-based and the dependency is dropped.
• PollingOptions.interval is number only (was string | number).
• Array arguments (answerInlineQuery results, sendMediaGroup media, sendInvoice prices, setMyCommands commands) no longer accept readonly arrays.

Added

• TypeScript — full type coverage for all API methods, options, and responses, bundled with the package (no separate @types/... install)
• Generated types — src/types/schemas.ts is generated from the live Bot API docs (npm run generate:types) as plain type aliases; the types are docs-faithful and carry no runtime validation
• ESM — the package is now ESM-only ("type": "module"); require() is no longer supported
• TelegramBotOptions type exported from the main entrypoint
• Type exports: ChatId, ParseMode, MessageEntity, ReplyMarkup, ReplyParameters, LinkPreviewOptions, SuggestedPostPrice, SuggestedPostInfo, SuggestedPostParameters, and all generated API types
• Node.js native test runner replaces Mocha
• sendLivePhoto method

Changed

• src/telegram.js → src/telegram.ts (full rewrite)
• src/telegramPolling.js → src/polling.ts
• src/telegramWebHook.js → src/webhook.ts
• src/errors.js → src/errors.ts
• src/utils.js → src/utils.ts
• test/ rewritten in TypeScript with node:test assertions
• Build output: lib/ → dist/

Removed

• CJS support — require('node-telegram-bot-api') no longer works; use import
• Mocha test infrastructure (test/mocha.opts, legacy test/telegram.js)
• Legacy lib/ output directory
• Legacy file-option param thumb — replaced by thumbnail
• Deprecated request option reply_to_message_id — use reply_parameters
• Legacy answerCallbackQuery(id, text, showAlert) / answerCallbackQuery([options]) signatures — use answerCallbackQuery(id, options)
• NTBA_FIX_350 environment flag — filename/contentType are now always auto-resolved

Fixed

• String errors now include timestamps in console output

Full Changelog: https://github.com/yagop/node-telegram-bot-api/compare/v0.67.0...v1.0.0