grammY tips

💡 Tip

You should always create a development bot with @BotFather in addition to the bot that you want your users to use. You can create up to 20 bots, and it is very helpful to have one that you can just play around with and start and stop without disrupting the operation of your real bot.

When you want to deploy to production, all you need to do is to swap out the token!

💡 Tip

You can easily run your handlers concurrently using bot.fork.

For example, if you know that you always want to answer callback queries with the same arguments, you can do this:

bot.on("callback_query:data")
.fork()
.use(ctx => ctx.answerCallbackQuery());
fork will make sure that subsequent handlers will still run, and that they will run concurrently. For example, with

bot.on("callback_query:data")
.fork()
.use(ctx => ctx.answerCallbackQuery());

bot.callbackQuery("greeting", ctx => ctx.reply("Hello!"));
you can make sure that the callback query will be answered and Hello! will be sent both at the same time, hence making your bot handle callback queries twice as fast!

🗣️ Story

Once, we discovered a bug in the core of Vue.js.

It all started because we wanted to justify the text on grammy.dev. This means that all lines have the same width, and words are broken up and squeezed and stretched to fit. Justified text is most often found in books and newspapers. However, it comes with a bunch of problems for technical documentation.

We sometimes have very long inline code snippets such as an example file identifier at https://grammy.dev/guide/files#how-files-work-for-telegram-bots. We also sometimes have long links like at https://grammy.dev/plugins/auto-retry#plugin-summary. Browsers are quite good at breaking up words in natural language (at least in English), but they cannot deal with elements like inline code snippets or URLs. And even if they did: it would be very strange to see a code snippet that goes like
await bot.api.send-
Message(chat_id, "hi");
because what is that hyphen in send-Message doing there???

Fortunately, there are tags in HTML. They indicate line break opportunities. Browsers are allowed to break text at these positions without inserting any hyphen. All we needed to do was to inject lots of tags at the right places into inline code snippets and URLs during the build process. This can be done with a bunch of incomprehensible regular expressions.

However, these invisible characters are apparently not very commonly used. At least, Vue.js had its problems with them. When grammy.dev was visited, the client-side hydration of Vue.js would sometimes accidentally duplicate parts of some paragraphs on duplicate parts of some paragraphs on grammy.dev.

Firstly, we reported this in a discussion on GitHub. At that point, we still believed it could be our strange regex that broke things.

Secondly, we were able to narrow it down even further to a very primitive website (without regex) that still had the same bug.

Thirdly, someone who knows a lot more about Vue.js than us opened a proper bug report based on our findings on the Vue.js core repo.

Lastly, Vue.js founder Evan You personally fixed the bug in this pull request which resulted in this commit. The Vue.js hydration tests covering our edge case contain bits of our reproduction example to this very day.

This story is a good example of open-source projects empowering each other. We use the entire frontend stack for free for our docs, and therefore we give back to the community behind it. Next time you use an open-source project for free, take a second to think about the thousands of stories like ours. They make possible what we all sometimes take for granted.

And now, get back to coding. 🤖

❗ Fact

The TypeScript type annotations modelling the Bot API are crafted by hand for grammY. Other bot libraries use scripts to scrape the website and generate type definitions automatically. We don't.

There are obvious advantages to automation. However, there are also several advantages to manual work, and they are often overlooked:
1. Writing down the types manually lets us find the perfect structure tailored towards how TypeScript works. We strive for quality above all. Being low maintenance is nice, but secondary.
2. Being able to apply the right structure to the underlying types is a source of inspiration for good abstractions built on top of the types. Filter queries likely would not have been possible without our novel way to declare the types internally.
3. When there are changes to the design of the Bot API website, we don't have to change anything about our setup.
4. It is trivial to start contributing. In contrast, automated scripts make it very hard for new contributors to join in.
5. It takes surprisingly little time to write down the types after each Bot API update. Even if it would take 10 hours every year to keep the types up to date (it is much less in reality), a very good automation for this task takes a lot more time to get right.

💡 Tip

Remember last week's post about Has Checks?

If you always want to check context objects for the same thing, you can create a predicate function once, and then apply it to many context objects. This is slightly more efficient. It can be done using Context.has—a static namespace for utility functions that create such filters.

const hasText = Context.has.filterQuery("message:text")

// later:
if (hasText(ctx)) {
const text = ctx.msg.text
}


Nifty!

💡 Tip

bot.on, bot.hears, and their siblings already let you filter down context objects without having to do large if statements. However, sometimes this just isn't enough, and you may want to do some extra branching inside a handler.

Did you know that you can do this via Has Checks? They let you find out lots of things for a context objects:

- Is there a start command in the update? ctx.hasCommand("start").
- Does the text match a regular expression? ctx.hasText(/regex/).
- Does the context match the filter query channel_post::hashtag? ctx.has("channel_post::hashtag").
- Many more!

This is especially useful inside the conversations plugin.

❗ Fact

Even though we love bots, there is no community management bot in @grammyjs, and we do not plan on adding one. That is because this place is for humans who work on code, not for code that works on humans.

You ask, how can you fight spam effectively if you do not automate it? It is quite simple: we just added a few more admins.

💡 Tip

If you just want to send a message or call any API method, you can use bot.api.sendMessage(chat_id, text) and the like. This just requires you to have access to your bot object.

Did you know that you can even perform any Bot API call with grammY without creating a bot at all? This can be done with the Api class:

const api = new Api("token");
await api.sendMessage(chat_id, text);


It even supports plugins that are based on API transformers:

api.config.use(autoRetry())


The instance of Api will be completely isolated from the rest of your project, so you could have different sets of transformers installed for different parts of your project! Be sure to check out this.

🗣️ Story

Once upon a time, a fix for a grammY plugin was ready to be implemented. When the plugin author asked for a pull request (PR) with the changes to be opened, he messed up: https://t.me/grammyjs/34357

To this day, we leave the term PR to the rest of the world. In our community, we say PQ.

❗ Fact

grammY is built to prevent programming mistakes.

While we try hard to design clean and intuitive APIs, it sometimes still happens that people accidentally use them incorrectly. grammY can detect some of the most common bugs and print warnings in debug mode. In more dangerous cases, it even throws an error right upfront so that your application does not randomly crash in production after a few weeks.

💡 Tip

As you likely know, you can use bot.on("message:text") to listen for text messages. There are many other filter queries so you can listen for exactly the updates you want.

However, did you know that the underlying filter query engine used by bot.on is exposed from grammY? The matchFilter function takes a filter query, compiles it, and builds a very efficient predicate function that you can use to test updates against the provided filter query.

This is especially powerful when combined with last week's tip:

// Listen for everything except forwards
bot.drop(matchFilter(':forward_date'), (ctx) => {
// ...
})

💡 Tip

Not only can you filter updates via bot.filter, there is also the opposite. With bot.drop, you can install handlers that run for all updates EXCEPT a few selected ones, namely those dropped by the custom predicate function. As an example, this handler will run for all photo messages except those that are sent inside a media group:

bot
.on(":photo")
.drop(
(ctx) => !!ctx.msg.media_group_id,
(ctx) => {
console.log("single photo!");
});

❗️ Fact

grammY runner is the fastest long polling implementation of all bot frameworks. Definitely of those bot frameworks written in a dynamic language. Probably also of all other bot frameworks. It can easily handle thousands of updates per second, which is about as much load as any Telegram bot ever gets.

This is achieved by a special design that decouples fetching updates from queuing and processing them, so the next batch of updates is always fetched immediately after the last byte of the previous batch has arrived. In addition, grammY runner supports automatic multi-threading which can distribute the work across several physical cores (something that is rarely seen with JavaScript).