Обработка обновлений
Start
Метод start
запускает процесс получения обновлений от Telegram для вашего бота. В зависимости от переданных параметров, бот может использовать long-polling или webhook для получения событий. Этот метод инициализирует бота, подгружает lazy плагины и вызывает хук onStart
.
Сигнатура:
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
).
- Если
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
, очищается очередь обновлений.
Сигнатура:
stop(timeout?): Promise<void>
Параметры:
timeout
— время ожидания завершения обработки очереди обновлений (по умолчанию 3000 мс).
Пример использования:
await bot.stop();
Описание работы:
- Останавливает long-polling или webhook (если был запущен).
- Дожидается завершения обработки всех текущих обновлений.
- Вызывает хук
onStop
.
Контекст
Прослушивание всех событий
bot.use((context, next) => {
// ...
});
Прослушивание только определенных событий
bot.on("message", (context, next) => {
// ...
});
// или
bot.on(["message", "callback_query"], (context, next) => {
// ...
});
Вы можете ознакомиться с API Reference для контекстов здесь.
Внедрение в контекст
Derive
Derive
позволяет внедрить в контекст что угодно, с доступом к существующим данным контекста и с проверкой типов. Обработчик будет вызываться при каждом обновлении.
Глобальный derive
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 для конкретного обновления (или обновлений) с полной поддержкой типов.
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.; //
})
.use((context, next) => {
if (context.is("message")) context.user;
return next();
})
.on("callback_query", (context) => {
context.user; context.fromId
});
Decorate
С помощью decorate
вы можете внедрить статические значения, и они будут внедрены в контексты только когда вызывается decorate
(т.е. они не будут вычисляться при каждом обновлении).
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; });