Update dependency telegraf to v4.16.3

[renovate]

This PR contains the following updates:

Package	Change	Age	Adoption	Passing	Confidence
telegraf (source)	4.9.0 -> 4.16.3

---

Release Notes

telegraf/telegraf (telegraf)

v4.16.3

Compare Source

• Fix: bug with link_preview_options.url caused client to try sending it as media
• Fix: add CommandContextExtn type to Composer::{start|help|settings} (adds ctx.command, payload, args)

v4.16.2

Compare Source

Fixed Context::text: was undefined if entities was undefined. Thanks to @​AnotiaWang.

v4.16.1

Compare Source

Fixed Context::from: now uses callbackQuery.from instead of msg.from

v4.16.0

Compare Source

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. Highlights are Reactions, Replies 2.0, Link Previews, Blockquotes, and Chat Boosts.
• Support for API 7.1.
• 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:

  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.reactions smart 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.setMessageReaction method 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.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.

  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!

  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.

  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.

  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.

  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.

  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 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 quote format helper for Blockquotes.
• 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.

v4.15.3

Compare Source

• Fix: unable to upload media
• Fix: thumbnail is now respected in all APIs that accept it

v4.15.2

Compare Source

EXPERIMENTAL_SESSION_CHECKS introduced in the last minor release had been reporting false positives. This has been fixed; it will now work as intended.

v4.15.1

Compare Source

• 🔧 Fixed sendPhoto and friends irrecoverably erroring if passed an invalid path, such as a directory.

• ⚠️ Set the env var EXPERIMENTAL_SESSION_CHECKS=1 to 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

Compare Source

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!

v4.14.0

Compare Source

• ⬆️ Bot API 6.9 support
• Added missing Markup.keyboard([]).persistent() method

v4.13.1

Compare Source

• Fix README to mention API 6.8

v4.13.0

Compare Source

👞👟🥾 Multi-session and custom session property

👞👟🥾 Multi-session and custom session property

This update brings us the ability to have multiple session keys. This is achieved simply by passing property in session options:

bot.use(session()); // creates ctx.session backed by an in-memory store

bot.use(session({
  property: "chatSession",
  getSessionKey: ctx => ctx.chat && String(ctx.chat.id),
  store: Redis({ url: "redis://127.0.0.1:6379" });
})); // creates ctx.chatSession backed by a Redis store

Thanks to @​Evertt for making the case for this feature.

📨 Command parser

📨 Command parser

It's an often requested feature to be able to parse command arguments.

As of this release, ctx.command, ctx.payload, and ctx.args are available for this usecase. It's only available in bot.command handlers.

ctx.command is the matched command (even if you used RegExp), and it does not include the botname if it was included in the user's command. ctx.payload is the unparsed text part excluding the command. ctx.args is a parsed list of arguments passed to it. Have a look at the example:

// User sends /warn --delete "Offtopic chat"

bot.command("warn", async ctx => {
  ctx.args; // [ "--delete", "Offtopic chat" ]

  ctx.command; // "warn"
  ctx.payload; // "--delete \"Offtopic chat\""
});

⚠️ ctx.args is still considered unstable, and the parser is subject to fine-tuning and improvements based on user feedback.

The more generic ctx.payload for all commands causes ctx.startPayload in bot.start to be redundant, and hence the latter is now deprecated.

bot.start(ctx => {
- console.log(ctx.startPayload);
+ console.log(ctx.payload);
});

You can also play with this feature by importing the parser directly:

import { argsParser } from "telegraf/utils";

// do not include the /command part!
argsParser('--delete "Offtopic chat"'); // [ "--delete", "Offtopic chat" ]

New types package

New types package

We have now forked Typegram to maintain types more in line with Telegraf.

Most of you will be unaffected, because Telegraf just switched its internal import to @telegraf/types. If you have a direct dependency on typegram for any reason, you might want to consider switching that over. typegram will continue to be maintained as well.

Remember that all of these types are available through Telegraf without installing any additional library:

import type { Update } from "telegraf/types";

This new package is @telegraf/types, available on Deno/x and npm with our ongoing effort to make Telegraf more platform independent.

⬆️ Bot API 6.6, 6.7, and 6.8 support

⬆️ Bot API 6.6, 6.7, and 6.8 support

We're a little delayed this time, but we've got them all ready for you now:

API 6.6

• New methods setMyDescription, getMyDescription, setMyShortDescription, getMyShortDescription, setCustomEmojiStickerSetThumbnail, setStickerSetTitle, deleteStickerSet, setStickerEmojiList, setStickerKeywords, setStickerMaskPosition
• Renamed setStickerSetThumb -> setStickerSetThumbnail
• Renamed thumb to thumbnail throughout the API
• Various other minor changes, refer to Bot API 6.6

API 6.7

• New methods setMyName, getMyName
• Various other minor changes, refer to Bot API 6.7

API 6.8

• New methods unpinAllGeneralForumTopicMessages
• Various other minor changes, refer to Bot API 6.8

More exciting updates coming soon!

v4.12.2

Compare Source

• Fix: session reference counter had defaulted to 0, therefore permanently being cached and never being cleaned up — this has been fixed.

v4.12.1

Compare Source

• Fix: bot.command did not match bot usernames if the registered username was not lowercased (#​1809)

v4.12.0

Compare Source

Normally the most exciting features of a new release would be support for the latest Bot API. But in this update, it's session! This has been in the works for many months, and we're happy to bring it to you this release!

🔒 Stable and safe session

Some of you may know that builtin session has been deprecated for quite a while. This was motivated by the fact that session is prone to race-conditions (#​1372). This left the community in a grey area where they continued to use session despite the deprecation, since no clear alternative was provided. Added to this was the fact that there were no official database-backed sessions, and all unofficial async session middleware were affected by #​1372.

This release finally addresses both of these long-running issues.

🏃🏼 No more race conditions

#​1713 provides a reference-counted implementation resistant to race conditions. Session is now no longer deprecated, and can be used safely!

Note: You should read more about how to safely use session in the docs repo.

™️ Official database adapters are here!

We're also happy to announce a revamped @telegraf/session—this provides official store implementations for database-backed sessions via Redis, MongoDB, MySQL, MariaDB, PostgreSQL, and SQLite. Just install the drivers necessary for your database, and off you go! Since this package now only provides a store implementation, it's usable with builtin session, and effectively makes all implementations have the same safety as the core package. Check it out!

🆗 Default session

Additionally, session now accepts a defaultSession parameter. You no longer need a hacky middleware to do ctx.session ??= { count }.

// 🤢 Old way
bot.use(session());
bot.use((ctx, next) => {
  ctx.session ??= { count: 0 };
  return next();
});

// 😁 New way ✅
bot.use(session({ defaultSession: () => ({ count: 0 }) }));

🔺 Bot API 6.5 support

• Updated Typegram, added the following Markup.button helpers to request a user or chat:
• Markup.button.userRequest
• Markup.button.botRequest
• Markup.button.groupRequest
• Markup.button.channelRequest
• Telegram::setChatPermissions and Context::setChatPermissions accept a new parameter for { use_independent_chat_permissions?: boolean } as documented in the API.

🔺 Bot API 6.4 support

• Updated Typegram, added the following new methods to class Telegram and Context:
• editGeneralForumTopic
• closeGeneralForumTopic
• reopenGeneralForumTopic
• hideGeneralForumTopic
• unhideGeneralForumTopic
• Context::sendChatAction will automatically infer message_thread_id for topic messages.
• Fix for 'this' Context of type 'NarrowedContext' is not assignable to method's 'this' of type 'Context<Update>'.

⚡️ RegExp support for commands!

Another long-standing problem was the lack of support for RegExp or case-insensitive command matching. This is here now:

bot.command("hello", ctx => ctx.reply("You sent a case-sensitive /hello"));
bot.command(/^hello$/i, ctx => ctx.reply("You sent a case-insensitive /hELLo"));

✍️ fmt helpers

• New join fmt helper to combine dynamic arrays into a single FmtString.

import { fmt, bold, join } from "telegraf/format";

// elsewhere
bot.command("/fruits", async ctx => {
  const array = ["Oranges", "Apples", "Grapes"];
  const fruitList = join(array.map(fruit => bold(fruit)), "\n");
  const msg = fmt`Fruits to buy:\n${fruitList}`;
  await ctx.sendMessage(msg);
});

• Fixed various bugs in fmt helpers, so things like bold(italic("telegraf")) will now work as expected.

🌀 Persistent chat actions

ctx.sendChatAction is used to send a "typing", or "uploading photo" status while your bot is working on something. But this is cleared after 5 seconds. If you have a longer process, you may want to keep calling sendChatAction in a loop. This new feature adds an API to help with this:

bot.command('/video', async ctx => {
  // starts sending upload_video action
  await ctx.persistentChatAction("upload_video", async () => {
    const data = await getLargeVideoSomehow();
    await ctx.sendVideo(Input.fromBuffer(data));
  }); // all done, stops sending upload_video
});

Thanks to @​orimiles5 for raising this pull request (#​1804).

Follow Telegraf_JS to receive these updates in Telegram. If you have feedback about this update, please share with us on @​TelegrafJSChat!

v4.11.2

Compare Source

• Fixed types for sendMediaGroup to accept StreamFile.
• Only send message_thread_id if is_topic_message is true.
  Telegram sends message_thread_id for reply messages, even if the group doesn't have topics. This caused the bot to throw when ctx.reply was used against reply messages in non-forums.

v4.11.1

Compare Source

• Fixed an issue where TypeScript was not able to import "telegraf/filters". Top-level filters.{js|d.ts} were missing in package.json "files" array.

v4.11.0

Compare Source

🔺 Bot API 6.3 support

• Updated to Typegram 4.1.0 and added the following new methods to Telegram class:
  • createForumTopic
  • editForumTopic
  • closeForumTopic
  • reopenForumTopic
  • deleteForumTopic
  • unpinAllForumTopicMessages
  • getForumTopicIconStickers
• Added new method shorthands to Context; add message_thread_id implicitly to Context::send* methods.

✨ Filters! ✨

We've added a new powerful feature called filters! Here's how to use them.

// import our filters
import { message, editedMessage, channelPost, editedChannelPost, callbackQuery } from "telegraf/filters";
// you can also use require, like this:
// const { message, editedMessage, channelPost, editedChannelPost, callbackQuery } = require("telegraf/filters");

const bot = new Telegraf(token);

bot.on(message("text"), ctx => {
  // this is a text message update
  // ctx.message.text
});

bot.on(channelPost("video"), ctx => {
  // this is a video channel post update
  // ctx.channelPost.video
});

bot.on(callbackQuery("game_short_name"), ctx => {
  // this is a callback_query game update
  // ctx.callbackQuery.game_short_name
});

This unlocks the ability to filter for very specific update types previously not possible! This is only an initial release, and filters will become even more powerful in future updates.

All filters are also usable from a new method, ctx.has. This is very useful if you want to filter within a handler. For example:

// handles all updates
bot.use(ctx => {
  if (ctx.has(message("text"))) {
    // handles only text messages
    // ctx.message.text;
  } else {
    // handles all other updates
  }
});

Like bot.on, ctx.has also supports an array of update types and filters, even mixed:

// match a message update or a callbackQuery with data present
bot.on(["message", callbackQuery("data")], handler);

if (ctx.has(["message", callbackQuery("data")])) {
  // ctx.update is a message update or a callbackQuery with data present
};

⚠️ Deprecating `bot.on` and `Composer::on` with message types!

As of this release, filtering by message type using bot.on() (for example: "text", "photo", etc.) is deprecated. Don't panic, though! Your existing bots will continue to work, but whenever you can, you must update your message type filters to use the above filters before v5. This is fairly easy to do, like this:

- bot.on("text", handler);
+ bot.on(message("text"), handler);

The deprecated message type behaviour will be removed in v5.

You might be happy, or fairly upset about this development. But it was important we made this decision. For a long time, Telegraf has supported filtering by both update type and message type.

This meant you could use bot.on("message"), or bot.on("text") (text here is a message type, and not an update type, so this was really making sure that update.message.text existed). However, when polls were introduced, this caused a conflict. bot.on("poll") would match both update.poll (update about stopped polls sent by the bot) and update.message.poll (a message that is a native poll). At type-level, both objects will show as available, which was wrong.

Besides, this type of filters really limited how far we could go with Telegraf. That's why we introduced filters, which are way more powerful and flexible!

⚠️ An important reminder

A few updates back, in 4.9.0, we added ctx.send* methods to replace ctx.reply* methods. This is because in v5 the behaviour of ctx.reply* will be to actually reply to the current message, instead of only sending a message.

To start using this behaviour right away, we had also introduced a middleware. We recommend you start using this, so that you're prepared for v5, which is brewing very soon!

import { useNewReplies } from "telegraf/future";

// this will enable ctx.reply throughout the bot to automatically reply to current message
// use ctx.sendMessage and friends to send a message without replying
bot.use(useNewReplies());

Other changes

• bot.launch is now catchable (#​1657)

  Polling errors were previously uncatchable in Telegraf. They are now. Simply attach a catch to bot.launch:

  bot.launch().catch(e => {
  // polling has errored
  });
  
  // You an also use await and try/catch if you're using ESM

  Three things to remember:

  • In case you're using bot.launch in webhook mode, it will immediately resolve after setWebhook completes.
  • This now means that bot.launch in polling mode will not resolve immediately. Instead, it will resolve after bot.stop(), or reject when there's a polling error.
  • The bot will not continue running after it errors, even if the error is caught. Before you create a new bot instance and launch it, consider that this error is fatal for a serious reason (for example: network is down, or bot token is incorrect). You may not want to attempt a restart when this happens.

  We previously did not want fatal errors to be caught, since it gives the impression that it's a handleable error. However, being able to catch this is useful when you launch multiple bots in the same process, and one of them failing doesn't need to bring down the process.

  Use this feature with care. :)

• Format helpers ("telegraf/format") now use template string substitution instead of naively using +=. (Discussion)

Follow Telegraf_JS to receive these updates in Telegram. If you have feedback about this update, please share with us on @​TelegrafJSChat!

v4.10.0

Compare Source

• Brand new formatting helpers! No more awkward escaping.

  import { fmt, bold, italics, mention } from "telegraf/format";
  
  ctx.reply(fmt`
  Ground control to ${mention("Major Tom", 10000000)}
  ${bold`Lock your Soyuz hatch`} and ${italic`put your helmet on`}
  — ${link("David Bowie", "https://en.wikipedia.org/wiki/David_Bowie")}
  `);

  This also just works with captions!

  ctx.replyWithPhoto(
    file.id,
    { caption: fmt`${bold`File name:`} ${file.name}` },
  );

• Added Input helpers to create the InputFile object.

  import { Telegraf, Input } from "telegraf";
  const bot = new Telegraf(token);
  
  bot.telegram.sendVideo(chatId, Input.fromLocalFile("../assets/cats.mp4"));
  
  bot.telegram.sendDocument(chatId, Input.fromBuffer(buf));
  
  bot.command("cat", ctx => {
    ctx.sendPhoto(Input.fromURL("https://funny-cats.example/cats.jpg"))
  });

  This helps clear the confusion many users have about InputFile.

• Deprecated ctx.replyWithMarkdown; prefer MarkdownV2 as Telegram recommends.

• Deprecated ctx.replyWithChatAction; use identical method ctx.sendChatAction instead.

• bot.launch()'s webhook options now accepts certificate for self-signed certs.

• Fix bot crashes if updateHandler throws (#​1709)

v4.9.2

Compare Source

• Fixed bad shorthand for ctx.replyWithVideo (#​1687)

v4.9.1

Compare Source

• Updated typegram to v3.11.0.

---

Configuration

📅 Schedule: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).

🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.

♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 Ignore: Close this PR and you won't be reminded about this update again.

---

• If you want to rebase/retry this PR, check this box

---

This PR was generated by Mend Renovate. View the repository job log.