Creating Telegram bots with GrammY

When we talk about modern applications, we inevitably end up running into the famous bots. Using bots to automate tasks, or even to make communicating with APIs easier, is becoming more and more common, and one of the platforms where bots keep popping up more and more is Telegram.

I personally hadn’t ventured much into the world of bots until recently, but in that adventure I found a fantastic tool that makes creating (and even revolutionizes) the way you build bots for Telegram: GrammY.

In this article we’re going to build a bot that searches GitHub repositories and sends them into a chat inline, meaning we’ll just type @bot and the repository name so it searches for the repository based on whatever we typed.

But first, let’s understand how a Telegram bot’s message flow actually works.

How a Telegram bot works#

Telegram is known worldwide for being a platform that’s simple both to use and to extend. And through extensions, we get several kinds of bots we can build, using the full power of the platform to create buttons, menus, and even entire sites that get shown back to users. Actually, a big chunk of Telegram itself runs on bots.

All of your bot’s interaction with Telegram happens based on a webhook, meaning that for every new event, whether it’s a new message or any other activity that happened directly with your bot or in some group it’s part of, a POST request gets sent to an address you define for the bot.

Your webhook address isn’t set by default, but we’ll define one a bit later with a specific endpoint.

Every type of message update on Telegram creates an event. This event can be one of the types described here in the docs. The response is always a JSON with an update_id key, and the next key is the type of event that was sent. For example, if we’re receiving an update for a message being sent, then we’re expecting an event of type message, so the payload we’ll get looks like this:

1
{
2
    "update_id": 821159882,
3
    "message": {
4
        "message_id": 1600269,
5
        "from": {
6
            "id": 172983467,
7
            "is_bot": false,
8
            "first_name": "Lucas",
9
            "last_name": "Santos",
10
            "username": "lhs_santoss",
11
            "language_code": "en"
12
        },
13
        "chat": {
14
            "id": 172983467,
15
            "first_name": "Lucas",
16
            "last_name": "Santos",
17
            "username": "lhs_santoss",
18
            "type": "private"
19
        },
20
        "date": 1664119114,
21
        "text": "Teste"
22
    }
23
}

Everything inside the message.from field relates to the user who sent the update event, and everything inside the message.chat key relates to the chat where the bot was triggered.

To answer a request, we can either respond to the update call itself with the result we want to send back (it could be another message, a keyboard, an inline query, and so on), or we can send a response directly to Telegram’s bot API, which is https://api.telegram.org/bot<token>/<method>, where the token is your bot’s token from BotFather and the method is one of the methods described here in the docs.

So I could send a message back to a user who sent me a message, on top of answering the original request, by using the request https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/sendMessage with the parameters described here.

Creating your first bot#

To start building a bot on Telegram, you first need to talk to another bot called BotFather. Just click this link to talk to it directly.

Then just type /newbot and answer the questions it asks you.

Remember that every Telegram bot needs a username that ends in bot, and it’s pretty hard to find a valid name that isn’t taken yet.

Once you’re done, the bot will reply with an access token, keep that token safe, because that’s what we’ll use to control your bot.If you want to understand this a bit more, the official docs have a full guide

With that done, let’s expose a local port to the cloud so we can connect our bot and test our messages. We can do that with ngrok, just download and install the NGROK binary and run the command:

1
ngrok http <your-port>

In my case I’ll be using 8000, so I’ll type ngrok http 8000, and ngrok’s response locks up your shell and gives you a link that looks something like https://<string>.<region>.ngrok.io, in my case it was https://fb83-80-216-0-139.eu.ngrok.io.

Using your favorite request tool (insomnia, postman), make a GET request to https://api.telegram.org/bot<token>/setwebhook?url=<yourngrokurl>, keeping in mind that the URL needs the full protocol in front of it, so in my case it would look like this:

1
https://api.telegram.org/bot1234512345:ABCDEFABCDEFABCDEFABCDEFABCDEF-AbcdefAbcdef/setwebhook?url=https://fb83-80-216-0-139.eu.ngrok.io

You should get a response like:

1
{
2
  "ok": true,
3
  "result": true,
4
  "description": "Webhook was set"
5
}

Now we can start coding our bot!

GrammY#

GrammY is a library built exclusively for creating Telegram bots, abstracting away the tedious part of having to manage the entire conversation context and flow by hand. On top of that it supports plugins and can be extended with a bunch of really cool features that make building a Telegram bot even easier.

If you want to check out the traditional way of building bots, take a look at this point in the repository of the bot we’re about to build:

And compare it with the final version we’re going to build in this article:

Deno#

GrammY is a framework built especially for use with Deno, and I personally think that’s fantastic because it lets you run TypeScript straight from the compiler, plus dependency resolution inside a Deno file, through modules being imported directly by URL, is a lot simpler and more direct.

So the first step is installing the Deno runtime on your machine to get access to the deno command.

Setting up the project#

To set up your environment using Deno, if you’re using VSCode, just install the official Deno extension and create a new folder, open that folder in VSCode and, using CTRL/CMD + SHIFT + P, look for “Deno Initialize workspace configuration”.

That’s going to create a new .vscode folder and a settings.json file inside it. Let’s leave it like this:

1
{
2
  "deno.enable": true,
3
  "deno.unstable": true,
4
  "editor.codeActionsOnSave": {
5
    "source.fixAll": true,
6
    "source.organizeImports": true
7
  },
8
  "editor.defaultFormatter": "denoland.vscode-deno"
9
}

Now let’s create the base files. This part comes down to taste, but I like creating a src folder with all the source files together and leaving the config files at the root.

Let’s start by creating the import-map.json file, which creates a mapping between base site names and libraries into a simpler alias, let’s leave it like this:

1
{
2
  "imports": {
3
    "x/": "https://deno.land/x/",
4
    "std/": "https://deno.land/std@0.156.0/"
5
  }
6
}

This tells Deno that whenever we import something like x/name it should replace x/ with https://deno.land/x/ plus our package name, just a shortcut so we don’t have to type out the whole site every time.

Now we can point Deno to this file and also create the equivalent of our NPM scripts in the deno.json file, which is the equivalent of package.json:

1
{
2
  "importMap": "./import-map.json",
3
  "tasks": {
4
    "start": "denon run -A ./src/utils/pooling.ts",
5
    "setWebhook": "deno run -A ./src/utils/setWebhook.ts"
6
  }
7
}

Here I have two tasks, one is start, which will boot up our bot, and the other is setWebhook, which will create the webhook programmatically the way we were doing before. We haven’t created either of them yet, but we will soon.

Notice I’m using denon, which is the Deno equivalent of nodemon, to install this package just run deno install -qAf --unstable https://deno.land/x/denon/denon.ts

With the setup done, let’s create an environment variables file called .env and put in the following variables:

1
BOT_SECRET="Any random string"
2
BOT_TOKEN="Your bot's token"
3
GH_API_TOKEN="A github token"

For BOT_SECRET, generate a sequence of 64 random characters, this is going to be a security key to guarantee your bot is who it says it is.

For BOT_TOKEN we’ll use the token BotFather gave us, and finally let’s head to GitHub to create a new token, it doesn’t need any permissions since we’re only going to use the API to search repositories, which doesn’t require any special access.

Building the bot#

First, let’s create the src folder and inside it a file that’s going to be our config file, from there we’ll pull in every system variable once. Let’s call this file config.ts:

1
import * as dotenv from 'std/dotenv/mod.ts'
2
await dotenv.config({ export: true })
3

4
export const config = {
5
  bot: {
6
    token: Deno.env.get('BOT_TOKEN') ?? '',
7
    secret: Deno.env.get('BOT_SECRET') ?? ''
8
  },
9
  gh: {
10
    token: Deno.env.get('GH_API_TOKEN') ?? ''
11
  }
12
}
13
export type AppConfig = typeof config

We’re importing dotenv, the module that loads environment variables straight from a .env file, notice we’re importing just std/dotenv instead of using the whole original URL path.

Next, let’s create a file that’ll make our lives easier whenever we need to set up our webhook again if we ever need to. Let’s create a utils folder and inside it a setWebhook.ts file.

In this file we’ll import the Bot object from GrammY, which represents the entire interface to Telegram’s bot API, and our config file.

1
import { Bot } from 'x/grammy@v1.11.0/mod.ts'
2
import { config } from '../config.ts'

Now let’s start a new bot with our token by calling the init function:

1
import { Bot } from 'x/grammy@v1.11.0/mod.ts'
2
import { config } from '../config.ts'
3

4
const bot = new Bot(config.bot.token)
5
await bot.init()

By default GrammY has an API that wraps every other Telegram API and creates an easy to use interface, but if you need or want to call a method directly from the API, you can use the bot.api object, which has every method with its parameters.

Remember we called https://bot.telegram.org/bot<token>/setWebhook? So let’s use the bot.api.setWebhook function and pass our program’s first parameter to it, also sending our bot’s secret, the whole file ends up like this:

1
import { Bot } from 'x/grammy@v1.11.0/mod.ts'
2
import { config } from '../config.ts'
3

4
const bot = new Bot(config.bot.token)
5
await bot.init()
6
await bot.api.setWebhook(Deno.args[0], { secret_token: config.bot.secret }).then(console.log)

Splitting off the search#

Since we’re building a bot to search GitHub, the idea is that we’ll type @ourbot <repository name>, and from there we can search by user or repository name with no problems, so let’s split this feature off from the rest of the bot to keep everything organized.

Let’s create a folder called core and inside it a gh.ts file. From here on we’ll use the fetch API to make calls directly to the GitHub API, but first let’s define our types.

A GitHub item has a response that looks like this:

1
export interface GHSearchItem {
2
  id: number
3
  name: string
4
  full_name: string
5
  owner: {
6
    login: string
7
    id: number
8
    avatar_url: string
9
    url: string
10
    html_url: string
11
  }
12
  html_url: string
13
  description: string
14
  fork: boolean
15
  stargazers_count: number
16
  watchers_count: number
17
  language: string
18
  forks_count: number
19
}

While the full API response result looks like this:

1
export interface GHSearchResult {
2
  total_count: number
3
  incomplete_results: boolean
4
  items: GHSearchItem[]
5
}

Now let’s create our search function, the idea is we’ll receive the parameter we’re searching for, strip the URL if there is one, and from there make the call to our endpoint and limit the result to 3 items at a time.

Our final file looks roughly like this:

1
import { config } from '../config.ts'
2

3
export interface GHSearchResult {
4
  total_count: number
5
  incomplete_results: boolean
6
  items: GHSearchItem[]
7
}
8

9
export interface GHSearchItem {
10
  id: number
11
  name: string
12
  full_name: string
13
  owner: {
14
    login: string
15
    id: number
16
    avatar_url: string
17
    url: string
18
    html_url: string
19
  }
20
  html_url: string
21
  description: string
22
  fork: boolean
23
  stargazers_count: number
24
  watchers_count: number
25
  language: string
26
  forks_count: number
27
}
28

29
export const search = async (query: string) => {
30
  const sanitized = query.replace('https://github.com/', '')
31
  const result = await fetch(`https://api.github.com/search/repositories?q=${sanitized}&per_page=3`, {
32
    method: 'GET',
33
    headers: {
34
      Accept: 'application/vnd.github.v3+json',
35
      Authorization: `Bearer ${config.gh.token}`
36
    }
37
  })
38
  return result.json() as Promise<GHSearchResult>
39
}

The bot#

Now, let’s get to the main part, our bot. For this let’s create a new file inside src called bot.ts, there we’ll put all the logic surrounding our bot and everything it needs to work and answer messages, but we won’t have it listening on the server just yet.

First let’s import the Bot class from GrammY, along with our config and the search interface we just built:

1
import { Bot } from 'x/grammy@v1.11.0/mod.ts'
2
import type { AppConfig } from './config.ts'
3
import { search } from './core/gh.ts'

Then let’s create a function called getBot, this function will hand us our bot already configured. The first thing we need to do is tell the bot we want to respond to a special kind of message called inline_query, which is when the user is typing directly in the message box.

For this, we’ll have to go back to Telegram and talk to BotFather again, because by default inline mode comes turned off on the bot, so we need to send the /setInline command, and BotFather will ask which bot you want to change the settings for, just pick one from the list.

After picking it, send the placeholder text that’ll show up while the user is searching in the next message, in our case it’ll be “Search GitHub Repos…”. And that’s it, we’re all set.

Now let’s go to our bot.ts file and create a listener for our message:

1
function getBot(config: AppConfig) {
2
  const bot = new Bot(config.bot.token)
3

4
  bot.on('inline_query', async (ctx) => {

Our ctx context object gets a bunch of properties from the Telegram request for us, like the query the user made, its type, ID and so on. And we’ll check whether the query is filled in, meaning whether the user has already typed something in the query, if not, we’ll respond with an empty array of results:

1
function getBot(config: AppConfig) {
2
  const bot = new Bot(config.bot.token)
3

4
  bot.on('inline_query', async (ctx) => {
5
    const { query } = ctx.inlineQuery
6
    if (!query) return ctx.answerInlineQuery([])

Here we’re using the ctx.answerInlineQuery command because we want the result to be answered as a list of results that shows up at the top of the text box, and not as a message, this method takes an array of results that follows a specific shape we’ll build once we have some result from GitHub.

If the user has already made a query, let’s pass that query on to GitHub and check whether we got any result, this is pretty simple because GitHub returns a total result count in the response:

1
function getBot(config: AppConfig) {
2
  const bot = new Bot(config.bot.token)
3

4
  bot.on('inline_query', async (ctx) => {
5
    const { query } = ctx.inlineQuery
6
    if (!query) return ctx.answerInlineQuery([])
7

8
    const results = await search(query)
9
    if (results.total_count <= 0) return ctx.answerInlineQuery([])

If we find something, let’s respond using ctx.answerInlineQuery with the result of a map over the GitHub results array, building our message.

The inline query response object follows this structure:

1
interface AnswerInlineQuery {
2
    type: 'article' // Fixed
3
    id: string // Unique ID for the response item
4
    title: string // Response title
5
    url: string // Response item URL
6
    cache_time?: number // How long the response stays cached on Telegram
7
    input_message_content: { // Content of the message sent when the response is selected
8
      message_text: string
9
        parse_mode: 'Markdown'|'HTML'|'MarkdownV2'
10
    }
11
    hide_url: boolean // Whether the URL should be hidden in the results list
12
    description: string // Result description
13
    thumb_url: string // Result thumbnail
14
}

We have all of this information straight from the GitHub API, we just need to build our object like this:

1
function getBot(config: AppConfig) {
2
  const bot = new Bot(config.bot.token)
3

4
  bot.on('inline_query', async (ctx) => {
5
    const { query } = ctx.inlineQuery
6
    if (!query) return ctx.answerInlineQuery([])
7

8
    const results = await search(query)
9
    if (results.total_count <= 0) return ctx.answerInlineQuery([])
10

11
    return ctx.answerInlineQuery(
12
      results.items.map((item) => ({
13
        type: 'article',
14
        id: item.id.toString(),
15
        title: item.full_name,
16
        url: item.html_url,
17
        cache_time: 300,
18
        input_message_content: {
19
          message_text: `[${item.full_name}](${item.html_url})
20
  _${item.description || 'No Description'}_
21

22
  *Stars:* ${item.stargazers_count}
23
  *Forks:* ${item.forks_count}
24
  *Language:* ${item.language}`,
25
          parse_mode: 'Markdown'
26
        },
27
        hide_url: true,
28
        description: item.description || 'No description',
29
        thumb_url: item.owner.avatar_url
30
      }))
31
    )

Notice I’m sending Markdown text in the message body, this text gets sent once the user selects that result. You can change this to return whatever you find coolest.

Finally we return the bot and export our function, the whole file ends up like this:

1
import { Bot } from 'x/grammy@v1.11.0/mod.ts'
2
import type { AppConfig } from './config.ts'
3
import { search } from './core/gh.ts'
4

5
function getBot(config: AppConfig) {
6
  const bot = new Bot(config.bot.token)
7

8
  bot.on('inline_query', async (ctx) => {
9
    const { query } = ctx.inlineQuery
10
    if (!query) return ctx.answerInlineQuery([])
11

12
    const results = await search(query)
13
    if (results.total_count <= 0) return ctx.answerInlineQuery([])
14

15
    return ctx.answerInlineQuery(
16
      results.items.map((item) => ({
17
        type: 'article',
18
        id: item.id.toString(),
19
        title: item.full_name,
20
        url: item.html_url,
21
        cache_time: 300,
22
        input_message_content: {
23
          message_text: `[${item.full_name}](${item.html_url})
24
  _${item.description || 'No Description'}_
25

26
  *Stars:* ${item.stargazers_count}
27
  *Forks:* ${item.forks_count}
28
  *Language:* ${item.language}`,
29
          parse_mode: 'Markdown'
30
        },
31
        hide_url: true,
32
        description: item.description || 'No description',
33
        thumb_url: item.owner.avatar_url
34
      }))
35
    )
36
  })
37
  return bot
38
}
39

40
export { getBot }

Putting it all together#

To glue every piece together, let’s create the src/mod.ts file, which is Deno’s main entry point. In it we’ll boot up our bot using webhooks, and for this we’ll need to import the webhookCallback function from GrammY, which exists exactly to set the bot up to listen to certain requests using a standard web server, in our case std/http.

First let’s import everything we need:

1
import { webhookCallback } from 'x/grammy@v1.11.0/mod.ts'
2
import { serve } from 'x/sift@0.5.0/mod.ts'
3
import { getBot } from './bot.ts'
4
import { config } from './config.ts'
5
const bot = getBot(config)

Now let’s set up our response handler for the server:

1
import { webhookCallback } from 'x/grammy@v1.11.0/mod.ts'
2
import { serve } from 'x/sift@0.5.0/mod.ts'
3
import { getBot } from './bot.ts'
4
import { config } from './config.ts'
5
const bot = getBot(config)
6

7
const handleUpdate = webhookCallback(bot, 'std/http', {
8
  secretToken: config.bot.secret
9
})

The handleUpdate function is what GrammY returns when we tell it to create a response object for bot using std/http as the server. That said, we’re not using Deno’s native module to create a web server, but Sift instead, which is a web framework for building servers without straying too far from Deno’s own defaults.

The idea is we have a serve function, just like we do in std/http, but we can pass a config object to this function, where each key is the route we’re listening on, and the key’s value is the response handler:

1
import { webhookCallback } from 'x/grammy@v1.11.0/mod.ts'
2
import { serve } from 'x/sift@0.6.0/mod.ts'
3
import { getBot } from './bot.ts'
4
import { config } from './config.ts'
5
const bot = getBot(config)
6

7
const handleUpdate = webhookCallback(bot, 'std/http', { secretToken: config.bot.secret })
8

9
serve({
10
  '/': (req) => {
11
    return req.method === 'POST' ? handleUpdate(req) : new Response('Not found', { status: 404 })
12
  }
13
})

Notice we’re always listening on the / route, and when we detect the route isn’t a POST, we respond with a 404 status, otherwise we pass our request on to the bot.

Testing locally#

To test locally we can start our bot with denon run -A ./src/mod.ts and it should already be listening successfully on whatever port we set.

If you get an error when running it, try caching the dependencies locally with deno cache --reload ./src/mod.ts or CMD + SHIFT + P in VSCode and look for “Deno: Cache” and select “Deno: Cache Dependencies”

Now just head over to Telegram and make requests using your bot’s @:

However, this method requires that we always have a URL to set our webhook to, which can be a problem, since that URL can change. Because of that, one of the best ways to test locally is to use a long polling setup instead, which will periodically check for new events on Telegram.

This is super simple, all we need to do is start our bot in a mode other than WebHooks, let’s create a new file at utils/pooling.ts:

1
import { getBot } from '../bot.ts'
2
import { config } from '../config.ts'
3

4
const bot = getBot(config)
5
bot.start({
6
  onStart: ({ username }) => console.log(`Bot started as @${username}`),
7
  drop_pending_updates: true
8
})

By default, GrammY’s bot.start will boot the bot in long polling mode, while you need to explicitly tell it to start in Webhook mode instead.

After that, just run our task in Deno with deno task start and we’ll get the same result.