• 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.

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 video channel post 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 messages
  }
});

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
};

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!

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());

• 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

  Two things to remember:

  • In case you're using bot.launch in webhook mode, it will immediately resolve after setWebhook completes.
  • 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)