Download Latest Version v4.16.3 source code.zip (160.1 kB)
Email in envelope

Get an email when there's a new version of telegraf.js

Home / v4.16.0
Name Modified Size InfoDownloads / Week
Parent folder
README.md 2024-02-24 10.2 kB
0
v4.16.0 source code.tar.gz 2024-02-24 133.3 kB
0
v4.16.0 source code.zip 2024-02-24 160.0 kB
0
Totals: 3 Items   303.6 kB 0

Phew, what a feature-packed release! 🎉

*tsk tsk* There's a big announcement at the end of this release!

🆙 Bot API Updates - Support for [API 7.0](https://core.telegram.org/bots/api-changelog#december-29-2023). Highlights are Reactions, Replies 2.0, Link Previews, Blockquotes, and Chat Boosts. - Support for [API 7.1](https://core.telegram.org/bots/api-changelog#february-16-2024). - All methods and update types from these API versions are now fully supported.
👍 Working with Reactions - To listen on reaction addition and removal, use `Composer.reaction`: ```TS bot.reaction("👍", (ctx) => { // user added a 👍 reaction }); // prefix with - to listen to reaction removal bot.reaction("-👍", (ctx) => { // user removed a 👍 reaction }); ``` This also just works with custom emoji IDs. ```TS bot.reaction("5368742036629364794", (ctx) => { // user added a reaction with the given custom emoji ID }); bot.reaction("-5368742036629364794", (ctx) => { // user removed a reaction with the given custom emoji ID }); ``` - You can probe and inspect the reaction list with the `ctx.reactions` smart object: ```TS bot.on("message_reaction", async (ctx) => { // remember that ctx.reactions is a smart object, but not an array // message has a 👍 reaction ctx.reactions.has("👍"); // message has a reaction with the given custom emoji ID ctx.reactions.has("5368742036629364794"); // number of reactions from this user on the message ctx.reaction.count; // indexed access is allowed: const first = ctx.reactions[0]; // the 👍 emoji was added in this update if (ctx.reactions.added.has("👍")) { // user added a 👍 reaction await User.updateOne({ id: ctx.from.id }, { $inc: { likes: 1 } }); } // the 👍 emoji was removed in this update if (ctx.reactions.removed.has("👍")) { // user removed a 👍 reaction await User.updateOne({ id: ctx.from.id }, { $inc: { likes: -1 } }); }; // to copy any of these smart objects into an array, call the `toArray` method const reactions = ctx.reactions.toArray(); const added = ctx.reactions.added.toArray(); const removed = ctx.reactions.removed.toArray(); }); ``` - To react to a message, use `ctx.react`: ```TS bot.on("text", async (ctx) => { await ctx.react("👍"); }); ``` You can also react to a message with a custom emoji ID: ```TS bot.on("text", async (ctx) => { await ctx.react("5368742036629364794"); }); ``` The `bot.telegram.setMessageReaction` method is also available.
💅 Context::text and Context::entities() helpers - Added the `ctx.entities()` method to fetch entities in any message. ```TS bot.on("text", (ctx) => { // fetch all entities const entities = ctx.entities(); // fetch all command entities const commandEntities = ctx.entities("bot_command"); // fetch all mentions and text mentions const mentions = ctx.entities("mention", "text_mention"); }); ``` Not only does this method fetch entities from any message, but also works with captions, game text, and poll explanations. In short, if an update has any text and entities, this method will find them. - `ctx.text` is the companion to `ctx.entities()`. It fetches the text from the update, and works with any message type. This includes message text, media captions, game text, and poll explanations. ```TS bot.on(message("text"), (ctx) => { // fetch the text from the update const text = ctx.text; }); bot.on(message("photo"), (ctx) => { // fetch the caption from the photo const caption = ctx.text; }); ``` - 🎁 Bonus! Every entity in the `ctx.entities()` array will have a fragment of the text they represent! ```TS bot.on("text", (ctx) => { const entities = ctx.entities("bold"); for (const entity of entities) { // the text that is bold const boldText = entity.fragment; } }); ```
📬 Context::msg and Context::msgId shorthands - `Context::msg` shorthand to get any message in the update. ```TS bot.use((ctx) => { // finds one of: // ctx.message ?? ctx.editedMessage ?? ctx.callbackQuery?.message ?? ctx.channelPost ?? ctx.editedChannelPost const msg = ctx.msg; }); ``` `ctx.msg` is decorated with the `isAccessible` and `has` methods. The `has` method works similarly to the `message()` filter in `bot.on`. It checks if the message has a certain property. ```TS if (ctx.msg.isAccessible()) { // msg is accessible, not deleted or otherwise unavailable // this is a type-guard based on the runtime check for msg.date === 0 } if (ctx.msg.has("text")) { // ctx.msg.text exists } ``` - `Context::msgId` shorthand to get any available message ID in the update. This also includes `message_id` present in updates that do not contain a message, such as `message_reaction`, and `message_reaction_count`. ```TS bot.use((ctx) => { // finds one of: // ctx.msg.message_id ?? ctx.messageReaction.message_id ?? ctx.messageReactionCount.message_id const msgId = ctx.msgId; }); ```
🚀 bot.launch takes an onLaunch callback - `bot.launch` now takes an optional callback that is called when the bot is launched. ```TS bot.launch(() => console.log("Bot is starting!")); ``` If you pass LaunchOptions, the callback goes after the options. ```TS bot.launch({ dropPendingUpdates: true }, () => console.log("Bot is starting!")); ``` This is useful for running some code when the bot is launched, such as logging to the console, or sending a message to a channel. Remember that errors thrown in this callback will not be caught by the bot's error handler. You must handle them yourself. > It's worth noting that the callback is called once the first `getMe` call is successful. This means network is working, and bot token is valid. Due to how networks work, there isn't a way to define when the bot is "fully" launched. The bot may still crash after the callback is called, for example if another instance of the bot is running elsewhere and polling `getUpdates` fails. For these reasons, onLaunch callback exists under `@experimental`, and may receive improvements based on feedback.
🖍 Format helpers - Added `blockquote` format helper. - Stricter types for format helpers. For example, it will now be a type-error to try to nest `pre` within another entity.
🔧 Other fixes and improvements - Added `ctx.match` for `Composer.command` (#1938). - Fixed thumbnail uploads in media groups (#1947). - The shorthand `ctx.chat` now includes `chat` from `this.messageReaction ?? this.messageReactionCount ?? this.removedChatBoost`. - The shorthand `ctx.from` now includes the field `user` from `ctx.messageReaction ?? ctx.pollAnswer ?? ctx.chatBoost?.boost.source`, in addition to fetching `from` in other updates. - `useNewReplies` uses `ctx.msgId` instead of `ctx.message.message_id` to reply to messages, which works for more update types than before. - The following modules are now directly importable: `types`, `scenes`, `filters`, `format`, `future`, `utils`, `markup`, `session`. For example, via `import { WizardScene } from "telegraf/scenes"`. This was previously available in v3, and was removed in v4.
💔 Minor breaking changes - (Breaking) `Markup.button.userRequest` will take `extra` instead of `user_is_premium` as the third parameter. - (Breaking) `Markup.button.botRequest` will take `extra` before `hide` as the third parameter. - (Types breaking) `reply_to_message_id` and `allow_sending_without_reply` replaced by `reply_parameters`. - (Types breaking) `disable_web_page_preview` and `link_preview_options` replaced by `link_preview_options`.
🎉 BIG announcement 🥳 ### Telegraf v4 - Last Major Update This will be the last major update for Telegraf v4. #### What to Expect If you are currently using Telegraf v4, you can continue using it as you have been. Telegraf v4 will be supported until February 2025, with the following commitments: - Bug fixes and security updates will still be released for Telegraf v4. - The existing documentation for Telegraf v4 will remain available. - New API updates will only focus on ensuring compatibility with the latest Telegram Bot API. No new convenience features will be added to Telegraf v4. #### Introducing Telegraf v5 In the coming weeks, we plan to release Telegraf v5. v5 will bring a revamped API, new functionalities, numerous convenient helpers, an improved approach to handling updates, and enhanced documentation. One of the key highlights of Telegraf v5 is its platform-agnostic nature, allowing you to run it on any JavaScript runtime environment, including Deno, Bun, edge runtimes (such as Cloudflare Workers and Vercel), browsers, and more. #### Smooth Transition to v5 If you have closely followed the development of v4 in the past year and stayed updated with deprecation notices, the transition to v5 will be relatively seamless for you. For those still using v4, we will provide a comprehensive migration guide to assist you in upgrading to v5. Stay tuned for more information on the release of v5!
Thanks for all the love ❤️! Go follow the releases channel on Telegram: t.me/Telegraf_JS.

You can sponsor the maintainer (@MKRhere) via GitHub Sponsors, Patreon, or Ko-fi.

Source: README.md, updated 2024-02-24