Repository navigation
Releases
v4.16.3
- Fix: bug with
link_preview_options.urlcaused client to try sending it as media - Fix: add
CommandContextExtntype toComposer::{start|help|settings}(adds ctx.command, payload, args)
v4.16.2
Fixed Context::text: was undefined if entities was undefined. Thanks to @AnotiaWang.
Contributors
Assets 2
v4.16.1
v4.16.0
Phew, what a feature-packed release! 🎉
*tsk tsk* There's a big announcement at the end of this release!
🆙 Bot API Updates
👍 Working with Reactions
-
To listen on reaction addition and removal, use
Composer.reaction: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.
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.reactionssmart object: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:bot.on("text", async (ctx) => { await ctx.react("👍"); });
You can also react to a message with a custom emoji ID:
bot.on("text", async (ctx) => { await ctx.react("5368742036629364794"); });
The
bot.telegram.setMessageReactionmethod is also available.
💅 Context::text and Context::entities() helpers
-
Added the
ctx.entities()method to fetch entities in any message.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.textis the companion toctx.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.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 p 8000 hoto const caption = ctx.text; });
-
🎁 Bonus! Every entity in the
ctx.entities()array will have a fragment of the text they represent!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::msgshorthand to get any message in the update.bot.use((ctx) => { // finds one of: // ctx.message ?? ctx.editedMessage ?? ctx.callbackQuery?.message ?? ctx.channelPost ?? ctx.editedChannelPost const msg = ctx.msg; });
ctx.msgis decorated with theisAccessibleandhasmethods. Thehasmethod works similarly to themessage()filter inbot.on. It checks if the message has a certain property.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::msgIdshorthand to get any available message ID in the update. This also includesmessage_idpresent in updates that do not contain a message, such asmessage_reaction, andmessage_reaction_count.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.launchnow takes an optional callback that is called when the bot is launched.bot.launch(() => console.log("Bot is starting!"));
If you pass LaunchOptions, the callback goes after the options.
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
getMecall 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 pollinggetUpdatesfails. For these reasons, onLaunch callback exists under@experimental, and may receive improvements based on feedback.
🖍 Format helpers
- Added
quoteformat helper for Blockquotes. - Stricter types for format helpers. For example, it will now be a type-error to try to nest
prewithin another entity.
🔧 Other fixes and improvements
- Added
ctx.matchforComposer.command(#1938). - Fixed thumbnail uploads in media groups (#1947).
- The shorthand
ctx.chatnow includeschatfromthis.messageReaction ?? this.messageReactionCount ?? this.removedChatBoost. - The shorthand
ctx.fromnow includes the fielduserfromctx.messageReaction ?? ctx.pollAnswer ?? ctx.chatBoost?.boost.source, in addition to fetchingfromin other updates. useNewRepliesusesctx.msgIdinstead ofctx.message.message_idto 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, viaimport { WizardScene } from "telegraf/scenes". This was previously available in v3, and was removed in v4.
💔 Minor breaking changes
- (Breaking)
Markup.button.userRequestwill takeextrainstead ofuser_is_premiumas the third parameter. - (Breaking)
Markup.button.botRequestwill takeextrabeforehideas the third parameter. - (Types breaking)
reply_to_message_idandallow_sending_without_replyreplaced byreply_parameters. - (Types breaking)
disable_web_page_previewandlink_preview_optionsreplaced bylink_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.
...
Contributors
Assets 2
v4.15.3
v4.15.2
v4.15.1
-
🔧 Fixed
sendPhotoand friends irrecoverably erroring if passed an invalid path, such as a directory. -
⚠️ Set the env varEXPERIMENTAL_SESSION_CHECKS=1to catch session bugs in your code.When this is enabled, Telegraf will throw errors if you access/assign to session after Telegraf thinks the middleware chain has exhausted. This can happen if you're missing awaits in async code, and session changes might not get persisted! Previously, these bugs were silently ignored until someone noticed their session was not saved. It's always safe to enable this feature. This behaviour may be default in v5.
v4.15.0
This is a rather minor release.
anyOf and allOf filter combinators
v4.11.0 introduced support for type-guard filters in Composer::on, which allowed you to filter updates based on their content.
This release adds two new combinators to the filter API: anyOf and allOf. This will play very nicely with custom filters. For example:
import { anyOf, allOf } from "telegraf/filters";
// must match all filters
bot.on(allOf(message(), isGroup), ctx => {
// ...
});Deprecating hookPath
The confusingly named hookPath in bot.launch webhook options is now deprecated. It will be removed in the next major release. You can start using path instead, today.
Meanwhile, we're working on new modules to add to the Telegraf ecosystem. Look forward to them, and join discussions in the official Telegraf chat!