Introduction

A Telegram bot is a special user account that is automated by a program. Anyone can create a Telegram bot, the only prerequisite is that you know a little bit of coding.

If you already know how create bots, head over to Getting Started!

grammY is a library that makes it super simple to write such a bot.

How to Write a Bot

Before you begin creating your bot, make yourself familiar with what Telegram bots can and cannot do. Check out the Introduction for Developers by the Telegram team.

In making your Telegram bot, you will create a text file with the source code of your bot. (You can also copy one of our example files.) It defines what your bot actually does, i.e. “when a user sends this message, respond with that”, and so on.

You can then run that source file. Your bot will now work, until you stop running it.

You’re kinda done now…

How to Keep a Bot Running

…except, if you are serious about your bot project. If you stop your bot (or shut down your computer), your bot becomes unresponsive, so it will no longer react to any messages.

Skip this section if you only want to play around with bots, and continue down here with the prerequisites to getting started.

Simply put, if you want the bot to be online all the time, you have to keep a computer running 24 hours every day. Because you most likely don’t want to do that with your laptop, you should upload your code to a hosting provider (in other words, someone else’s computer, also known as a server), and let those people run it for you.

There are countless companies that let you run your Telegram bot for free. This documentation covers a number of different hosting providers that we know work well with grammY (check the Resources). In the end, however, the choice of which provider to pick is up to you. Remember that running your code somewhere else means that whoever owns that “somewhere” has access to all your messages and the data of your users, so you should pick a provider that you can trust.

Here is a (simplified) diagram of how the setup will look in the end when Alice contacts your bot:

_________        sends a         ____________                    ____________
| Alice | —> Telegram message —> | Telegram | —> HTTP request —> | your bot |
—————————      to your bot       ————————————                    ————————————

 a phone                        Telegram servers                  your laptop,
                                                                better: a server


|____________________________________________|                   |___________|
                    |                                                  |
        Telegram's responsibility                             your responsibility

Similarly, your bot can make HTTP requests to the Telegram servers to send messages back to Alice. (If you have never heard of HTTP, you can think of it as the data packages that are sent through the internet, for now.)

What grammY Does for You

Bots interact with Telegram via HTTP requests. Every time your bot sends or receives messages, HTTP requests go back and forth between the Telegram servers and your server/computer.

At its core, grammY implements all of this communication for you, so you can simply type sendMessage in your code and a message will be sent. In addition, there are a variety of other helpful things that grammY does to make it simpler to create your bot. You will get to know them as you go.

Prerequisites to Getting Started

Skip the rest of this page if you already know how to develop a Deno or a Node.js application, and get started.

Here are a few interesting things about programming—things that are essential to coding, yet rarely explained because most developers think they are self-evident.

In the next section, you will create a bot by writing a text file that contains source code in the programming language TypeScript. The grammY documentation will not teach you how to program, so we expect you to teach yourself. Remember, though: creating a Telegram bot with grammY is actually a good way to learn coding! 🚀

Learning How to Code

You can start learning TypeScript with the official tutorial written by the TypeScript team, and then move on from there. Don’t spend more than 30 minutes reading things on the internet, then come back here, (read the rest of the section) and get started.

If you see unfamiliar syntax in the docs, or if you get an error message that you don’t understand, google it—the explanation is already on the internet (e.g. on StackOverflow).

Not Learning How to Code

Save yourself some time by watching this 34 second long video.

By picking grammY, you have already decided on a programming language, namely TypeScript. But what happens once you’ve created your TypeScript code, how will it start running? For that, you need to install some software which is able to execute your code. This type of software is called a runtime environment. It takes in your source code files and actually does whatever is programmed in them.

For us, there are two runtime environments to choose from, Deno and Node.js. (If you see people call it Node, they are just too lazy to type “.js”, but they mean the same thing.)

The rest of this section helps you decide between these two platforms. If you already know what you want to use, jump down to the prerequisites for Node.js or those for Deno.

Node.js is the older, more mature technology. If you need to connect to a funky database or do other low-level system-related things, chances are extremely high that you can do it with Node.js. Deno is relatively new, so it is sometimes still lacking support for some advanced things. Today, most servers use Node.js.

On the other hand side, Deno is significantly easier to learn and to use. If you don’t have much experience with programming yet, it makes sense to start with Deno.

Even if you have written code for Node.js before, you should consider giving Deno a go. Many things that are hard under Node.js are a no-brainer under Deno. It has

• no package.json file to configure,
• no node_modules to maintain,
• superior, built-in development tools,
• substantially better security, and
• many more advantages that do not fit here.

Developing code under Deno is also a lot more fun. At least, that’s our opinion.

However, if you have a reason to use Node.js, for example because you already know it well, then that is completely fine! We are making sure that grammY works equally well on both platforms, and we are not cutting any corners. Please choose what you think is best for you.

Prerequisites for Deno

Install Deno if you have not done that already. When you have created your bot, for example in a file called bot.ts, you can run it via deno run --allow-net bot.ts. You can stop it again with Ctrl+C.

Ready? Get started! 🤖

Prerequisites for Node.js

You are going to write your bot in TypeScript, but, contrary to Deno, Node.js cannot actually run TypeScript. Instead, once you have a source file (e.g. called bot.ts), you are going to compile it to JavaScript. You will then have two files: your original bot.ts, and a generated bot.js, which can in turn be run by Node.js. The exact commands for all of that will be introduced in the next section when you actually create a bot, but it is important to know that these steps are necessary.

In order to run the bot.js file, you have to have Node.js installed.

In summary, this is what you have to do for Node.js:

1. Create a source file bot.ts with TypeScript code, e.g. using VSCode (or any other code editor).
2. Compile the code by running a command in your terminal. This generates a file called bot.js.
3. Run bot.js using Node.js, again from your terminal.

Every time you modify your code in bot.ts, you need to restart the Node.js process. Hit Ctrl+C in your terminal to stop the process. This will stop your bot. Then, you need to repeat steps 2 and 3.

Are you ready? Get started! 🤖