Bot API

Документация Telegram Bot API

Bot API - это высокоуровневый HTTP-интерфейс к Telegram API, который упрощает разработку ботов. Под капотом Bot API использует TDLib (который, в свою очередь, использует MTProto API).

В то время как Bot API может использоваться только для работы с аккаунтами ботов, MTProto API может использоваться для работы как с ботами, так и с аккаунтами пользователей. Если вам необходимо работать с MTProto, мы рекомендуем библиотеку mtcute.

Вызов Bot API

Вы можете вызывать методы Telegram Bot API через bot.api или через сокращенные методы контекстов (например, context.send - это сокращение для sendMessage)

const response = await bot.api.sendMessage({
    //
    //
    chat_id: "@gramio_forum",
    text: "текст сообщения",
});

bot.on("message", (context) =>
    context.send("Это сообщение будет отправлено в текущий чат")
);

Подавление ошибок

Бывает удобно обрабатывать ошибку на месте без использования блоков try/catch. Для этого был создан аргумент suppress, который можно использовать в любом методе API.

const response = await bot.api.sendMessage({
    //
    //
    suppress: true,
    chat_id: "@not_found",
    text: "Метод с подавлением ошибок",
});

if (response instanceof TelegramError)
    console.error("sendMessage вернул ошибку...");
else console.log("Сообщение успешно отправлено");

Обработка Rate-Limit

По умолчанию, GramIO не обрабатывает 429 (rate limit) ошибки, но предоставляет утилиту для их обработки.

import { withRetries } from "gramio/utils";

const response = await withRetries(() =>
    bot.api.sendMessage({
        chat_id: "@gramio_forum",
        text: "текст сообщения",
    })
);
response;

withRetries будет ждать необходимое время указанное в retryDelay у ошибки TelegramError и только после успешного выполнения запроса, вернет результат.

Этот метод ловит выброшенную или возвращенную ошибку TelegramError так что вы можете использовать и с context.* или своими обёртками.

Подробнее о rate limits

Типы

GramIO реэкспортирует @gramio/types (кодо-генерируемые и автоматически публикуемые типы Telegram Bot API).

Подробнее

import type { APIMethodParams, APIMethodReturn } from "gramio";

type SendMessageParams = APIMethodParams<"sendMessage">;
//

type GetMeReturn = APIMethodReturn<"getMe">;
//

Например, вы можете использовать их в вашей собственной функции.

function myCustomSend(params: APIMethodParams<"sendMessage">) {
    params;
}

Типы для методов с подавлением ошибок

import type {
    SuppressedAPIMethodParams,
    SuppressedAPIMethodReturn,
} from "gramio";

type SendMessageParams = SuppressedAPIMethodParams<"sendMessage">;
//

type GetMeReturn = SuppressedAPIMethodReturn<"getMe">;
//

Отладка

Для отладки запросов, которые отправляет GramIO, вы можете установить переменную окружения DEBUG=gramio:api:*

npx cross-env DEBUG=gramio:api:* node index.js

И вы увидите что-то подобное в консоли:

gramio:api:getUpdates options: {"method":"POST","headers":{"Content-Type":"application/json"},"body":"{\"offset\":0,\"suppress\":true}"} +0ms
gramio:api:getUpdates response: {"ok":true,"result":[]} +49ms

Также, если вы используете Bun, вы можете использовать переменную окружения BUN_CONFIG_VERBOSE_FETCH для логирования сетевых запросов. Подробнее.

BUN_CONFIG_VERBOSE_FETCH=curl bun src/index.ts

И логи будут выглядеть так:

[fetch] > HTTP/1.1 POST https://example.com/
[fetch] > content-type: application/json
[fetch] > Connection: keep-alive
[fetch] > User-Agent: Bun/1.1.14
[fetch] > Accept: */*
[fetch] > Host: example.com
[fetch] > Accept-Encoding: gzip, deflate, br
[fetch] > Content-Length: 13

[fetch] < 200 OK
[fetch] < Accept-Ranges: bytes
[fetch] < Cache-Control: max-age=604800
[fetch] < Content-Type: text/html; charset=UTF-8
[fetch] < Date: Tue, 18 Jun 2024 05:12:07 GMT
[fetch] < Etag: "3147526947"
[fetch] < Expires: Tue, 25 Jun 2024 05:12:07 GMT
[fetch] < Last-Modified: Thu, 17 Oct 2019 07:18:26 GMT
[fetch] < Server: EOS (vny/044F)
[fetch] < Content-Length: 1256

Оптимизация старта вместе с Bun: --fetch-preconnect

Если вы запускаете своего бота с помощью Bun, вы можете использовать CLI-флаг --fetch-preconnect=<url>, чтобы ускорить первый сетевой запрос к серверам Telegram. Этот флаг сообщает Bun начать устанавливать соединение (DNS, TCP, TLS) с указанным хостом до запуска вашего кода, чтобы первый API-запрос был быстрее.

Пример:

bun --fetch-preconnect=https://api.telegram.org:443/ ./src/bot.ts

Это особенно полезно для ботов, где первое действие — обращение к Telegram API. С этим флагом Bun "разогреет" соединение на этапе старта, и ваш бот будет готов отправлять запросы с меньшей задержкой. Общее время старта может немного увеличиться, но время до первого успешного API-запроса уменьшится. В основном это не мешает, но меньше ощущается когда первый запрос отправляется сразу после запуска процесса.

Подробнее в документации Bun.