Writing an interactive Telegram bot using Claudia.js

Here at Rate, you’ll find all sorts of people. Most recently, I’ve had the opportunity to get to know one of the queerer bunch — a steadfast and determined individual who works round-the-clock, and never seems to eat, sleep, or even get paid at all! He is our resident Telegram bot, and you can say “hi” (or more accurately, /start) to him over on Telegram at @Rate3_Honey_Bot.

The Honey Bot (made for our Honey Program) is written with the help of the Claudia.js bot builder. Claudia is a handy tool that automatically writes boilerplate code for you, parses incoming requests into a common format, and adapts your outputs into the relevant structures for each platform. This means that you only need to come up with the business logic for your bot, and then easily deploy them to any platform you like. Note: Claudia.js deploys only to AWS Lambda.

I will not be providing instructions on how to set-up and deploy a bot through Claudia.js (you can check out their GitHub and web tutorial for information on that), but instead this article will describe the basic workings of Claudia and the Telegram Bot API so that you can start coming up with bot ideas for Telegram and quickly get down to implementing them, the way you want it to be.

Here we go!

Let’s start simple. The most basic of bots require very little code:

Now you have a bot that replies Hello, World! to anything the user says!

Well, that was really fun and interactive.

Of course, this is hardly useful. How about being a little bit more reactive?

Much better.

Right, now how does it work?

Receiving messages

When a user sends a message to the bot, Claudia receives it through the WebHook that she set up for you, and wraps it up nicely in a message object, the contents of which can be found here. We’ll only be using two of those today:

text: string the text of the message received, extracted from a bot-specific format.

originalRequest: object the complete original message, in a bot-specific format, useful if you want to do more than just reply to text messages.

The text object is an easy way to retrieve the message sent to the bot, while originalRequest contains the full details of the message as per Telegram’s Message object, where we can extract a variety of information like the user’s name, as demonstrated above.

Replying messages

When you return a string, Claudia formats it into the proper response object for the platforms you specified (in this case, Telegram), and your bot sends that string as a text reply back to the user.

Alternatively, if you take a look at Telegram’s sendMessage API method, you’ll find a few optional fields which you can use to customize your message. To utilize these, simply return an object containing the respective fields instead of a string, and Claudia will send it to the sendMessage API.

Markdown support!

Special keyboards

What happens if you have recalcitrant users (like me) who love talking to bots in all sorts of ways? Instead of employing Natural Language Processing, there’s a much simpler and easier way to solve this problem — keyboards.

Keyboards allow you to display predefined replies for your users to pick from and interact with your bot. It still won’t stop them from typing whatever they want, but at least they will know not to expect anything to happen from those invalid messages.

Reply keyboards

These keyboards replace the usual text keyboard with buttons that have text replies on it. Pressing these buttons will cause the users to send the exact text message into the chat.

resize_keyboard removes excess space within the button so that it looks nice and snug.

You can have multiple buttons on each row!

Note that the keyboard does not disappear automatically. You have the option of making it a one_time_keyboard, but the name is a misnomer — it merely hides the keyboard after use; users can still choose to bring it back up. To permanently remove the keyboard, you’ll have to send another message and include { remove_keyboard: true } in the reply_markup field.

The keyboard is removed when the bot sends the reply.

Inline keyboards

The other kind of keyboard available to us. There are two main differences:

1. The button appears below the bot’s messages.
2. There are additional functionalities these buttons can have.

Let’s try out one of those new functions: the callback button.

The callback feature makes the button work very similar to the reply keyboard button. Instead of having the user send a text message when the button is pressed, the string data is instead silently sent to the bot and is found in the text field of the incoming message from Claudia.

Pressing the buttons in order.

Instead of callback_data, you may also supply a url which will make the button open a link upon being clicked. There are also more advanced features like switch_inline_query and callback_game which you can read about in the docs, that allow a wider variety of bots to function.

telegramTemplate

There’s a slightly cleaner way to respond with a keyboard — using telegramTemplate, courtesy of Claudia. The template also has some other cool, unique features like the Pause(), which… well, pauses the bot for a while before executing the next action, and makes the humans less suspicious of the fact that they’re talking to a bot. Beep boop.

You can send multiple messages in a row by putting them in an array!

The second message is sent after a 1-second delay.

You can also modify the fields like disable_web_page_preview or parse_mode directly in the telegramTemplate object to achieve the full range of customisation that Telegram offers.

API calls

Q: What’s better than a bot that sends hard-coded messages?

A: A bot that sends hard-coded messages… from your back-end!

You can make your bot even more useful by allowing it to communicate with your server or any other online service. I recommend the minimal-promise-request library to reduce overhead and make HTTP requests easy to write.

If only it were that easy…

With this, you can have your bot act as the front-end to any server, and allow users to access a service without ever leaving Telegram!

Editing messages

Now that you know how to make HTTP requests, let’s make our bot even slicker. Say you have a bot that replies with an inline keyboard. When users make a selection, your bot would normally send the reply as a new message, but what if you wanted to show a sub-menu instead? It would be much nicer to replace the existing menu with the new one, and we can do just that with another Telegram method. The editMessageText lets you edit messages like a real user can, allowing you to replace your entire message with a whole new one if you wanted to.

Interacting with your bot now feels more like an app. Here’s how it would look like:

What’s next?

You’re now equipped with enough skills to start writing a bot of your own, so go out there and make something fun and interactive! There’s so much you can do with an easy way to grab a user’s message, access to a customizable reply format, and the ability to communicate with an API.

Once you’re comfortable with these options, continue to explore the Telegram bot API for even more things that you can play around with. Soon, you’ll have a bot that works beautifully and can give your users a great experience right from their mobile phones.

Happy botting!

Useful resources

• The entire Telegram bot API — https://core.telegram.org/bots/api
• Claudia.js — https://claudiajs.com/
• Quickly deploying Claudia.js — https://aws.amazon.com/blogs/compute/create-and-deploy-a-chat-bot-to-aws-lambda-in-five-minutes/
• minimal-request-promise — https://www.npmjs.com/package/minimal-request-promise
• Bots built with Claudia.js — https://github.com/claudiajs/claudia-bot-builder#cool-things-built-with-claudia-bot-builder