Skip to content

Обработка обновлений

Start

Метод start запускает процесс получения обновлений от Telegram для вашего бота. В зависимости от переданных параметров, бот может использовать long-polling или webhook для получения событий. Этот метод инициализирует бота, подгружает lazy плагины и вызывает хук onStart.

Сигнатура:

ts
start(options?): Promise<BotInfo>

Параметры:

  • options — объект с настройками запуска:
    • webhook — параметры для запуска через webhook (true, строка-URL или объект с параметрами).
    • longPolling — параметры для long-polling (например, таймауты).
    • dropPendingUpdates — сбрасывать ли неотправленные обновления при запуске.
    • allowedUpdates — список типов обновлений, которые бот будет получать.
    • deleteWebhook — как поступать с существующим webhook при запуске long-polling.

IMPORTANT

Особенности параметров:

  • Если указать webhook: true, GramIO не будет пытаться установить webhook самостоятельно — предполагается, что вы уже настроили его. В этом случае бот просто начнёт принимать обновления через уже существующий webhook.

  • Параметр deleteWebhook управляет тем, что делать с существующим webhook при запуске long-polling:

    • Если deleteWebhook: true, бот всегда удаляет webhook перед запуском long-polling.
    • Если deleteWebhook: "on-conflict-with-polling", webhook будет удалён только если он мешает запуску long-polling (когда Telegram отвечает на запрос getUpdates с ошибкой конфликта).
    • Если не указано, используется поведение по умолчанию (on-conflict-with-polling).
ts
import { Bot } from "gramio";

const bot = new Bot(process.env.BOT_TOKEN)
    .command("start", (ctx) => ctx.send("Привет!"))
    .onStart(console.log);

await bot.start({
    longPolling: { timeout: 10 },
    dropPendingUpdates: true,
});

Описание работы:

  • Если не указан webhook, запускается long-polling.
  • Если указан webhook, настраивается webhook и бот начинает принимать обновления через HTTP.
  • Вызывает хук onStart.
  • Можно сбросить старые обновления при запуске.

Stop

Метод stop завершает приём обновлений и корректно останавливает все внутренние процессы бота. Вызывается хук onStop, очищается очередь обновлений.

Сигнатура:

ts
stop(timeout?): Promise<void>

Параметры:

  • timeout — время ожидания завершения обработки очереди обновлений (по умолчанию 3000 мс).

Пример использования:

ts
await bot.stop();

Описание работы:

  • Останавливает long-polling или webhook (если был запущен).
  • Дожидается завершения обработки всех текущих обновлений.
  • Вызывает хук onStop.

Контекст

Прослушивание всех событий

ts
bot.use((context, next) => {
    // ...
});

Прослушивание только определенных событий

ts
bot.on("message", (context, next) => {
    // ...
});
// или
bot.on(["message", "callback_query"], (context, next) => {
    // ...
});

Вы можете ознакомиться с API Reference для контекстов здесь.

Внедрение в контекст

Derive

Derive позволяет внедрить в контекст что угодно, с доступом к существующим данным контекста и с проверкой типов. Обработчик будет вызываться при каждом обновлении.

Глобальный derive

ts
import { 
Bot
} from "gramio";
const
bot
= new
Bot
(
process
.
env
.
BOT_TOKEN
as string)
.
derive
((
context
) => {
return {
key
: 1,
}; }) .
on
("message", (
context
) => {
context
.
key
;
}) .
use
((
context
,
next
) => {
context
.
key
;
return
next
();
}) .
on
("callback_query", (
context
) => {
context
.
key
;
});

Ограниченный (scoped) derive

Вы можете ограничить derive для конкретного обновления (или обновлений) с полной поддержкой типов.

ts
import { 
Bot
} from "gramio";
// Простой пример export function
findOrRegisterUser
(
id
: number) {
return {} as
Promise
<{
id
: number;
name
: string;
balance
: number }>;
} const
bot
= new
Bot
(
process
.
env
.
BOT_TOKEN
as string)
.
derive
(["message", "callback_query"], async (
context
) => {
const
fromId
=
context
?.
from
?.
id
;
if(!
fromId
) throw new
Error
("No from id");
return {
fromId
,
} }) .
derive
("message", async (
context
) => {
const
user
= await
findOrRegisterUser
(
context
.
fromId
);
return {
user
,
}; }) .
on
("message", (
context
) => {
context
.
user
.
;
Identifier expected.
// }) .
use
((
context
,
next
) => {
if (
context
.
is
("message"))
context
.
user
;
return
next
();
}) .
on
("callback_query", (
context
) => {
context
.
user
;
Property 'user' does not exist on type 'CallbackQueryContext<Bot<{}, DeriveDefinitions & { message: { fromId: number; }; callback_query: { fromId: number; }; } & { message: { user: { id: number; name: string; balance: number; }; }; }>> & { ...; }'.
context
.
fromId
});

Decorate

С помощью decorate вы можете внедрить статические значения, и они будут внедрены в контексты только когда вызывается decorate (т.е. они не будут вычисляться при каждом обновлении).

ts

import { 
Bot
} from "gramio";
const
bot
= new
Bot
(
process
.
env
.
BOT_TOKEN
as string)
.
decorate
("TEST", "привет!! ты милашка" as
const
)
.
decorate
({
key
: "значение",
key2
: "значение",
}) .
use
((
context
) => {
context
.
TEST
;
//
context
.k
;
Property 'k' does not exist on type 'Context<Bot<{}, DeriveDefinitions & { global: { TEST: "привет!! ты милашка"; }; } & { global: { key: string; key2: string; }; }>> & { TEST: "привет!! ты милашка"; } & { ...; }'.
});