grammY

Bot API

General Information

Telegram bots communicate with the Telegram servers via HTTP requests. The Telegram Bot API is the specification of this interface, i.e. a long listopen in new window of methods and data types, commonly called a reference. It defines everything that Telegram bots can do. You can find it linked under the Resources tab.

The setup can be visualized like this:

( ( ( Telegram ) MTProto API ) Bot HTTP API ) <-- bot connects here

In words: when your bot sends a message, it will be sent as an HTTP request to a Bot API server (either hosted by the Telegram team, or hosted by youopen in new window). This server will translate the request to Telegram’s native protocol called MTProto, and send a request to the Telegram backend which takes care of sending the message to the user.

Analogously, whenever a user responds, the inverse path is taken.

Circumventing File Size Limits

The Telegram backend allows your bot to send files up to 2000 MB. However, the Bot API server that is responsible for translating the requests to HTTP restricts the file size to 50 MB for downloads and 20 MB for uploads.

Hence, if you circumvent the Bot API server that Telegram runs for you, and simply host your own Bot API serveropen in new window, you can allow your bot to send files up to 2000 MB.

Note: if you are working with large files over long polling, you should use grammY runner.

Calling the Bot API

Every single method of the Bot API has an equivalent in grammY. Example: sendMessage in the Telegram Bot API Referenceopen in new window and in the grammY API Referenceopen in new window.

Calling a Method

You can call API methods via bot.api, or equivalently via ctx.api:

async function sendHelloTo12345() {
  // Send a message to 12345.
  await bot.api.sendMessage(12345, "Hello!");

  // Send a message and store the response, which contains info about the sent message.
  const sentMessage = await bot.api.sendMessage(12345, "Hello again!");
  console.log(sentMessage.message_id);
}

While bot.api covers the entire Bot API, it sometimes changes the function signatures a bit to make it more usable. Strictly speaking, all methods of the Bot API expect a JSON object with a number of properties. Notice, however, how sendMessage in the above example receives two arguments, a chat identifier and a string. grammY knows that these two values belong to the chat_id and the text property, respectively, and will built the correct JSON object for you.

As mentioned earlier, you can specify other options in the third argument of type Other:

async function sendHelloTo12345() {
  await bot.api.sendMessage(12345, "<i>Hello!</i>", {
    parse_mode: "HTML",
  });
}

Moreover, grammY takes care of numerous technical details to simplify the API usage. As an example, some specific properties in some specific methods have to be JSON.stringifyed before they are sent. This is easy to forget, hard to debug, and it breaks type inference. grammY allows you to specify objects consistently across the API, and makes sure that the right properties are serialized on the fly before sending them.

Making Raw API Calls

There may be times when you want to use the original function signatures, but still rely on the convenience of the grammY API (e.g. JSON serialising where appropriate). grammY supports this via the bot.api.raw (or the ctx.api.raw) properties.

You can call the raw methods like this:

async function sendHelloTo12345() {
  await bot.api.raw.sendMessage({
    chat_id: 12345,
    text: "<i>Hello!</i>",
    parse_mode: "HTML",
  });
}

Basically, all parameters of the function signature are merged with the options object when you use the raw API.