Skip to main content

Telegram Bots 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 list

of methods and data types, commonly called a reference. It defines everything that Telegram bots can do.

Bots API in telegram fully based on MTProto, but because using MTProto be difficult form developers, Telegram provide Bots API based on HTTP request which translate HTTP calls to MTProto requests.

It looks something like this:

Bots API

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 you. 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.

Telegram Bots API server limits

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 server , you can allow your bot to send files up to 2000 MB.

Not all methods are available​

Telegram bots API not implements all available API methods, but you can call these methods using User API with authorization by bot token.

For example, bots can't get user info by User ID, or get channel participants, but bots can get it when authorized in User API

note

Opengram not implements MTProto API, but you can use GramJS or other solutions which uses TDLib

Calling the Bot API​

Calling a Method​

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

bot.on('message', async ctx => {
    await ctx.telegram.sendMessage(12345678, "Hello!");

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

While bot.telegram 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. Opengram knows that these two values belong to the chat_id and the text property, respectively, and will build the correct JSON object for you.

As mentioned earlier, you can specify other options in the third argument with extra arguments:

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

Moreover, Opengram 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. Opengram allows you to specify objects consistently across the API, and makes sure that the right properties are serialized on the fly before sending them.

note

Opengram supports calling API requests via the bot.telegram.callApi (or the ctx.telegram.callApi) properties.

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

Example:

ctx.telegram.callApi('sendMessage', { chat_id: 12345678, text: '<b>Hello!</b>', parse_mode: 'HTML' })

Limits​

tip

Telegram does not officially talk about many limits, but you can use an unofficial source such as Telegram info

  • Files​

    • With Local Bots API Server​

      2000 MB per file for download / upload

    • Without Local Bots API Server​

      20 MB for download revived files 50 MB for upload files

  • Markup​
    • Up to 10 KB for Markup (inline buttons and etc.)
    • Up to 100 commands in commans list (setted by BotFather or with setMyCommands)
  • Payload​
    note

    64 bytes != 64 symbols, for exmaple one Emoji = 2-4 bytes