unjs/untun.
**Untun** is a tool for tunnel your **local** HTTP(s) server to the world!
> [!IMPORTANT]
> Examples of starting with a specific framework are omitted. See [this example](#example).
### via API
This method allows you to set a link to our tunnel directly in the script.
Install package:
::: code-group
```bash [npm]
npm install untun
```
```bash [yarn]
yarn add untun
```
```bash [pnpm]
pnpm install untun
```
```bash [bun]
bun install untun
```
:::
Start tunnel and set webhook:
```ts
import { startTunnel } from "untun";
const tunnel = await startTunnel({ port: 3000 });
bot.start({
webhook: {
url: await tunnel.getURL(),
},
});
```
### via CLI
We are listening to port `3000` locally. Therefore, we open the tunnel like this:
::: code-group
```bash [npm]
npx untun@latest tunnel http://localhost:3000
```
```bash [yarn]
yarn dlx untun@latest tunnel http://localhost:3000
```
```bash [pnpm]
pnpm dlx untun@latest tunnel http://localhost:3000
```
```bash [bun]
bunx untun@latest tunnel http://localhost:3000
```
:::
```bash
◐ Starting cloudflared tunnel to http://localhost:3000
ℹ Waiting for tunnel URL...
✔ Tunnel ready at https://unjs-is-awesome.trycloudflare.com
```
Now we use this link when installing the webhook:
```ts
bot.start({
webhook: {
url: "https://unjs-is-awesome.trycloudflare.com",
},
});
```
## Write you own updates handler
```ts
// a non-existing framework for the example
import { App } from "some-http-framework";
import { Bot } from "gramio";
const bot = new Bot(process.env.BOT_TOKEN as string).on("message", (context) =>
context.send("Hello!")
);
// init is required. It is used for lazy-load plugins, and also receives information about the bot.
await bot.init();
const app = new App().post("/telegram", async (req) => {
// req.body must be json equivalent to TelegramUpdate
await bot.updates.handleUpdate(req.body);
});
app.listen(80);
```
---
---
url: /plugins/official/i18n.md
---
# I18n plugin
[](https://www.npmjs.org/package/@gramio/i18n)
[](https://jsr.io/@gramio/i18n)
[](https://jsr.io/@gramio/i18n)
`i18n` plugin for [GramIO](https://gramio.dev/).
This plugin provide internationalization for your bots with [Fluent](https://projectfluent.org/) syntax.
You can [setup type-safety](#type-safety) for it.
`i18n` plugin for [GramIO](https://gramio.dev/).
This plugin provide good way to add internationalization for your bots! It can be used without GramIO, but it will always keep it in mind.
> [!IMPORTANT]
> Since `1.0.0`, we have two ways to write localization: [`I18n-in-TS`](#i18n-in-ts-syntax) and [`Fluent`](#fluent-syntax)
### Installation
For [I18n-in-TS syntax](#i18n-in-ts-syntax)
::: code-group
```bash [npm]
npm install @gramio/i18n
```
```bash [bun]
bun add @gramio/i18n
```
```bash [yarn]
yarn add @gramio/i18n
```
```bash [pnpm]
pnpm add @gramio/i18n
```
:::
For [Fluent syntax](#fluent-syntax)
::: code-group
```bash [npm]
npm install @gramio/i18n @fluent/bundle
```
```bash [bun]
bun add @gramio/i18n @fluent/bundle
```
```bash [yarn]
yarn add @gramio/i18n @fluent/bundle
```
```bash [pnpm]
pnpm add @gramio/i18n @fluent/bundle
```
:::
## I18n-in-TS syntax
This syntax allows you to write localization without leaving `.ts` files and does not require code-generation for **type-safety**, as well as provides convenient integration with the Format API out of the box!
```ts twoslash
import { format, Bot } from "gramio";
import {
defineI18n,
type LanguageMap,
type ShouldFollowLanguage,
} from "@gramio/i18n";
const en = {
greeting: (name: string) => format`Hello, ${name}!`,
and: {
some: {
nested: "Hi!!!",
},
},
} satisfies LanguageMap;
const ru = {
greeting: (name: string) => format`Привет, ${name}!`,
and: {
some: {
nested: "Hi!!!",
},
},
} satisfies ShouldFollowLanguage
[](https://www.npmjs.org/package/@gramio/media-cache)
[](https://jsr.io/@gramio/media-cache)
[](https://jsr.io/@gramio/media-cache)
`Media cache` plugin for [GramIO](https://gramio.dev/).
This plugin caches the sent `file_id`'s and prevents files from being uploaded again.
Currently, **sendMediaGroup** is not cached.
## Usage
```ts
import { Bot } from "gramio";
import { mediaCache } from "@gramio/media-cache";
const bot = new Bot(process.env.BOT_TOKEN as string)
.extend(mediaCache())
.command("start", async (context) => {
return context.sendDocument(
await MediaUpload.url(
"https://raw.githubusercontent.com/gramiojs/types/main/README.md"
)
);
})
.onStart(console.log);
bot.start();
```
---
---
url: /plugins/official/media-group.md
---
# Media group plugin
[](https://www.npmjs.org/package/@gramio/media-group)
[](https://jsr.io/@gramio/media-group)
[](https://jsr.io/@gramio/media-group)
This plugin collects `mediaGroup` from messages (**1** attachment = **1** message) using a **delay** if `mediaGroupId` is in the **MessageContext**, pass only **first** message further down the middleware chain with the `mediaGroup` key, which contains an **array** of messages of this **mediaGroup** (it also contains the **first** message).
```ts
import { Bot } from "gramio";
import { mediaGroup } from "@gramio/media-group";
const bot = new Bot(process.env.BOT_TOKEN as string)
.extend(mediaGroup())
.on("message", async (context) => {
if (!context.mediaGroup) return;
return context.send(
`Caption from the first message - ${context.caption}. MediaGroup contains ${context.mediaGroup.length} attachments`
);
})
.onStart(({ info }) => console.log(`✨ Bot ${info.username} was started!`));
bot.start();
```
### Installation
::: code-group
```bash [npm]
npm install @gramio/media-group
```
```bash [yarn]
yarn add @gramio/media-group
```
```bash [pnpm]
pnpm add @gramio/media-group
```
```bash [bun]
bun install @gramio/media-group
```
:::
### Setup
You can change the duration of the delay in milliseconds by simply passing it like this:
```typescript
const bot = new Bot(process.env.BOT_TOKEN as string)
.extend(mediaGroup(1000)) // wait 1 second for message with mediaGroupId (refreshed after new message with it)
.on("message", async (context) => {
if (!context.mediaGroup) return;
return context.send(
`Caption from the first message - ${context.caption}. MediaGroup contains ${context.mediaGroup.length} attachments`
);
})
.onStart(({ info }) => console.log(`✨ Bot ${info.username} was started!`));
bot.start();
```
By default it `150 ms`.
---
---
url: /files/media-input.md
---
# Media Input
Class-helper with static methods that represents the content of a media message to be sent.
[API Reference](https://jsr.io/@gramio/files/doc)
[Documentation](https://core.telegram.org/bots/api/#inputmedia)
## document
Represents a general file to be sent.
```ts twoslash
// @errors: 2345
import { BotLike, MessageContext } from "gramio";
import { MediaInput, MediaUpload } from "@gramio/files";
const ctx = {} as InstanceType
[](https://www.npmjs.org/package/@gramio/prompt)
[](https://jsr.io/@gramio/prompt)
[](https://jsr.io/@gramio/prompt)
A plugin that provides [Prompt](#prompt) and [Wait](#wait) methods
### Installation
::: code-group
```bash [npm]
npm install @gramio/prompt
```
```bash [yarn]
yarn add @gramio/prompt
```
```bash [pnpm]
pnpm add @gramio/prompt
```
```bash [bun]
bun install @gramio/prompt
```
:::
## Usage
```ts
import { Bot, format, bold } from "gramio";
import { prompt } from "@gramio/prompt";
const bot = new Bot(process.env.BOT_TOKEN as string)
.extend(prompt())
.command("start", async (context) => {
const answer = await context.prompt(
"message",
format`What's your ${bold`name`}?`
);
return context.send(`✨ Your name is ${answer.text}`);
})
.onStart(console.log);
bot.start();
```
## Prompt
### Prompt with text + params
```ts
const answer = await context.prompt("What's your name?");
// or with SendMessageParams
const answer = await context.prompt("True or false?", {
reply_markup: new Keyboard().text("true").row().text("false"),
});
```
answer is `MessageContext` or `CallbackQueryContext`
### Prompt with text + params and the specified event
```ts
const answer = await context.prompt("message", "What's your name?");
const answer = await context.prompt("callback_query", "True or false?", {
reply_markup: new InlineKeyboard()
.text("true", "true")
.row()
.text("false", "false"),
});
```
answer is `CallbackQueryContext`
### Validation
You can define a handler in params to validate the user's answer.
If handler returns false, the message will be repeated.
```ts
const answer = await context.prompt(
"message",
"Enter a string that contains russian letter",
{
validate: (context) => /[а-яА-Я]/.test(context.text),
//... and some SendMessageParams
}
);
```
### Transform
```ts
const name = await context.prompt(
"message",
format`What's your ${bold`name`}?`,
{
transform: (context) => context.text || context.caption || "",
}
);
```
name is `string`
## Wait
### Wait for the next event from the user
```ts
const answer = await context.wait();
```
answer is `MessageContext` or `CallbackQueryContext`
### Wait for the next event from the user ignoring events not listed
```ts
const answer = await context.wait("message");
```
answer is `CallbackQueryContext`
### Wait for the next event from the user ignoring non validated answers
You can define a handler in params to validate the user's answer.
If handler return `false`, the **message** will be ignored
```ts
const answer = await context.wait((context) => /[а-яА-Я]/.test(context.text));
// or combine with event
const answer = await context.wait("message", (context) =>
/[а-яА-Я]/.test(context.text)
);
```
### Wait for the next event from the user ignoring non validated answers with transformer
You can define a handler in params to **transform** the user's answer.
```ts
const answer = await context.wait((context) => /[а-яА-Я]/.test(context.text));
// or combine with event
const answer = await context.wait("message", {
validate: (context) => /[а-яА-Я]/.test(context.text),
transform: (context) => c.text || "",
});
```
answer is `string`
---
---
url: /keyboards/remove-keyboard.md
---
# Remove Keyboard
Upon receiving a message with this object, Telegram clients will remove the current custom keyboard and display the default letter-keyboard. By default, custom keyboards are displayed until a new keyboard is sent by a bot. An exception is made for one-time keyboards that are hidden immediately after the user presses a button (see [ReplyKeyboardMarkup](https://core.telegram.org/bots/api/#replykeyboardmarkup)).
See also [API Reference](https://jsr.io/@gramio/keyboards/doc/~/RemoveKeyboard).
## Import
### With GramIO
```ts twoslash
import { RemoveKeyboard } from "gramio";
```
### Without GramIO
```ts twoslash
import { RemoveKeyboard } from "@gramio/keyboards";
```
## Options ([Documentation](https://core.telegram.org/bots/api/#replykeyboardremove))
These parameters are responsible for the settings of the removal buttons
### selective
Use this parameter if you want to remove the keyboard for specific users only.
Targets:
1. users that are \@mentioned in the
_text_ of the [Message](https://core.telegram.org/bots/api/#message) object.
2. if the bot's message is a reply to a message in the same chat and forum topic, sender of the original message.
Example: A user votes in a poll, bot returns confirmation message in reply to the vote and removes the keyboard for that user, while still showing the keyboard with poll options to users who haven't voted yet.
```ts twoslash
import { RemoveKeyboard } from "@gramio/keyboards";
// ---cut---
new RemoveKeyboard().selective(); // to enable
new RemoveKeyboard().selective(false); // to disable
```
---
---
url: /keyboards/keyboard.md
---
# Keyboard
This keyboard is shown under the input field and also known as Reply/Custom Keyboard.
Represents a [custom keyboard](https://core.telegram.org/bots/features#keyboards) with reply options (see [Introduction to bots](https://core.telegram.org/bots/features#keyboards) for details and examples).
See also [API Reference](https://jsr.io/@gramio/keyboards/doc/~/Keyboard)
## Import
### With GramIO
```ts twoslash
import { Keyboard } from "gramio";
```
### Without GramIO
```ts twoslash
import { Keyboard } from "@gramio/keyboards";
```
## Buttons ([Documentation](https://core.telegram.org/bots/api/#keyboardbutton))
Buttons are methods that assemble a keyboard for you.
### text
Text button. It will be sent as a message when the button is pressed
```ts twoslash
import { Keyboard } from "@gramio/keyboards";
// ---cut---
new Keyboard().text("some button text");
```
### requestUsers
Request users button. Pressing the button will open a list of suitable users. Identifiers of selected users will be sent to the bot in a `users_shared` service message. Available in private chats only. `Second parameter` is signed 32-bit identifier of the request that will be received back in the [UsersShared](https://core.telegram.org/bots/api/#usersshared) object. Must be unique within the message
```ts twoslash
import { Keyboard } from "@gramio/keyboards";
// ---cut---
new Keyboard().requestUsers("some button text", 228, {
user_is_premium: true,
});
```
More about options in [documentation](https://core.telegram.org/bots/api/#keyboardbuttonrequestusers)
### requestChats
Request users button. Pressing the button will open a list of suitable chats. Tapping on a chat will send its identifier to the bot in a `chat_shared` service message. Available in private chats only.. Available in private chats only. `Second parameter` is signed 32-bit identifier of the request, which will be received back in the [ChatShared](https://core.telegram.org/bots/api/#chatshared) object. Must be unique within the message
```ts twoslash
import { Keyboard } from "@gramio/keyboards";
// ---cut---
new Keyboard().requestChat("gramio", 255, {
chat_is_forum: true,
});
```
> [!WARNING]
> By default, the `chat_is_channel` parameter is false!
More about options in [documentation](https://core.telegram.org/bots/api/#keyboardbuttonrequestchat)
### requestPoll
Request poll button. Pressing the button will open a list of suitable users. Identifiers of selected users will be sent to the bot in a `users_shared` service message. Available in private chats only.
```ts twoslash
import { Keyboard } from "@gramio/keyboards";
// ---cut---
new Keyboard().requestPoll("some button text", "quiz");
```
More about options in [documentation](https://core.telegram.org/bots/api/#keyboardbuttonpolltype)
### requestLocation
Request user's location button. The user's current location will be sent when the button is pressed. Available in private chats only.
```ts twoslash
import { Keyboard } from "@gramio/keyboards";
// ---cut---
new Keyboard().requestLocation("some button text");
```
### requestContact
Request contact button. The user's phone number will be sent as a contact when the button is pressed. Available in private chats only.
```ts twoslash
import { Keyboard } from "@gramio/keyboards";
// ---cut---
new Keyboard().requestContact("some button text");
```
### webApp
webApp button. Described [Web App](https://core.telegram.org/bots/webapps) will be launched when the button is pressed. The Web App will be able to send a `web_app_data` service message. Available in private chats only.
```ts twoslash
import { Keyboard } from "@gramio/keyboards";
// ---cut---
new Keyboard().webApp("some button text", "https://...");
```
## Options ([Documentation](https://core.telegram.org/bots/api/#replykeyboardmarkup))
These parameters are responsible for the settings of the buttons
### resized
Requests clients to resize the keyboard vertically for optimal fit (e.g., make the keyboard smaller if there are just two rows of buttons). If `false`, in which case the custom keyboard is always of the same height as the app's standard keyboard. Defaults to `true`.
```ts twoslash
import { Keyboard } from "@gramio/keyboards";
// ---cut---
new Keyboard().text("some text").resized(); // to enable
new Keyboard().text("some text").resized(false); // to disable
```
> [!WARNING]
> The buttons are resized by default! To cancel this, use `.resized(false)`
### oneTime
Requests clients to hide the keyboard as soon as it's been used. The keyboard will still be available, but clients will automatically display the usual letter-keyboard in the chat - the user can press a special button in the input field to see the custom keyboard again. Defaults to `false`.
```ts twoslash
import { Keyboard } from "@gramio/keyboards";
// ---cut---
new Keyboard().text("some text").oneTime(); // to enable
new Keyboard().text("some text").oneTime(false); // to disable
```
### persistent
Requests clients to always show the keyboard when the regular keyboard is hidden. Defaults to `false`, in which case the custom keyboard can be hidden and opened with a keyboard icon. Defaults to `false`.
```ts twoslash
import { Keyboard } from "@gramio/keyboards";
// ---cut---
new Keyboard().text("some text").persistent(); // to enable
new Keyboard().text("some text").persistent(false); // to disable
```
### persistent
Use this parameter if you want to show the keyboard to specific users only.
Targets:
1. users that are \@mentioned in the _text_ of the [Message](https://core.telegram.org/bots/api/#message) object.
2. if the bot's message is a reply to a message in the same chat and forum topic, sender of the original message.
_Example:_ A user requests to change the bot's language, bot replies to the request with a keyboard to select the new language. Other users in the group don't see the keyboard. Defaults to `false`.
```ts twoslash
import { Keyboard } from "@gramio/keyboards";
// ---cut---
new Keyboard().text("some text").selective(); // to enable
new Keyboard().text("some text").selective(false); // to disable
```
### placeholder
The placeholder to be shown in the input field when the keyboard is active. 1-64 characters. Defaults to `not to be`.
```ts twoslash
import { Keyboard } from "@gramio/keyboards";
// ---cut---
new Keyboard().text("some text").placeholder("some text"); // to enable
new Keyboard().text("some text").placeholder(); // to disable
```
## Helpers
Methods that help you build a keyboard.
### row
Adds a `line break`. Call this method to make sure that the next added buttons will be on a new row.
```ts twoslash
import { Keyboard } from "@gramio/keyboards";
// ---cut---
new Keyboard().text("first row").row().text("second row");
```
### columns
Allows you to limit the number of columns in the keyboard.
```ts twoslash
import { Keyboard } from "@gramio/keyboards";
// ---cut---
new Keyboard()
.columns(1)
.text("first row")
.text("second row")
.text("third row");
```
### wrap
A custom handler that controls row wrapping.
```ts twoslash
import { Keyboard } from "@gramio/keyboards";
// ---cut---
new Keyboard()
.wrap(({ button }) => button.text === "second row")
.text("first row")
.text("first row")
.text("second row");
```
handler is
```ts
(options: { button: T; index: number; row: T[]; rowIndex: number }) => boolean;
```
### pattern
An array with the number of columns per row. Allows you to set a «template».
```ts twoslash
import { Keyboard } from "@gramio/keyboards";
// ---cut---
new Keyboard()
.pattern([1, 3, 2])
.text("1")
.text("2")
.text("2")
.text("2")
.text("3")
.text("3");
```
### filter
A handler that helps filter keyboard buttons.
```ts twoslash
import { Keyboard } from "@gramio/keyboards";
// ---cut---
new Keyboard()
.filter(({ button }) => button.text !== "hidden")
.text("pass")
.text("hidden")
.text("pass");
```
### add
Allows you to add multiple buttons in _raw_ format.
```ts twoslash
import { Keyboard } from "@gramio/keyboards";
// ---cut---
const labels = ["some", "buttons"];
new Keyboard()
.add({ text: "raw button" })
.add(Keyboard.text("raw button by Keyboard.text"))
.add(...labels.map((x) => Keyboard.text(x)));
```
### addIf
Allows you to dynamically substitute buttons depending on something.
```ts twoslash
// @noErrors
import { Keyboard } from "@gramio/keyboards";
// ---cut---
const labels = ["some", "buttons"];
const isAdmin = true;
new Keyboard()
.addIf(1 === 2, { text: "raw button" })
.addIf(isAdmin, Keyboard.text("raw button by Keyboard.text"))
.addIf(
({ index, rowIndex }) => rowIndex === index,
...labels.map((x) => Keyboard.text(x))
);
```
handler is
```ts
(options: { rowIndex: number; index: number }) => boolean;
```
### matrix
Allows you to create a button matrix.
```ts twoslash
// @noErrors
import { Keyboard } from "@gramio/keyboards";
// TODO: remove no errors
// ---cut---
import { randomInt } from "node:crypto";
const bomb = [randomInt(0, 9), randomInt(0, 9)] as const;
new Keyboard().matrix(10, 10, ({ rowIndex, index }) =>
Keyboard.text(rowIndex === bomb[0] && index === bomb[1] ? "💣" : "ㅤ")
);
```
The result is keyboard with a bomb on a random button
handler is
```ts
(options: { index: number; rowIndex: number }) => T;
```
### combine
Allows you to combine keyboards. Only keyboards are combined. You need to call the `.row()` method to line-break after combine.
```ts twoslash
import { Keyboard } from "@gramio/keyboards";
// ---cut---
new Keyboard()
.combine(new Keyboard().text("first"))
.row()
.combine(new Keyboard().text("second").row().text("third"));
```
---
---
url: /plugins/official/scenes.md
---
# @gramio/scenes
[](https://www.npmjs.org/package/@gramio/scenes)
[](https://jsr.io/@gramio/scenes)
[](https://jsr.io/@gramio/scenes)
The API can be changed a little, but we already use it in production environment.
# Usage
```ts twoslash
import { Bot } from "gramio";
import { scenes, Scene } from "@gramio/scenes";
export const greetingScene = new Scene("greeting")
.params<{ test: boolean }>()
.step("message", (context) => {
if (context.scene.step.firstTime)
return context.send("Hi! What's your name?");
if (!context.text) return context.send("Please write your name");
return context.scene.update({
name: context.text,
});
})
.step("message", (context) => {
if (context.scene.step.firstTime)
return context.send("How old are you?");
const age = Number(context.text);
if (!age || Number.isNaN(age) || age < 0)
return context.send("Please write your age correctly");
return context.scene.update({
age,
});
})
.step("message", async (context) => {
await context.send(
`Nice to meet you! I now know that your name is ${
context.scene.state.name
} and you are ${context.scene.state.age} years old. ${
context.scene.params.test ? "Also you have test param!" : ""
// ^?
}`
);
return context.scene.exit();
});
const bot = new Bot(process.env.TOKEN as string)
.extend(scenes([greetingScene]))
.command("start", async (context) => {
return context.scene.enter(greetingScene, {
test: true,
});
});
```
### Share state between steps
```ts twoslash
import { Scene } from "@gramio/scenes";
const testScene = new Scene("test")
.step("message", async (context) => {
if (context.scene.step.firstTime || context.text !== "1")
return context.send("1");
return context.scene.update({
messageId: context.id,
some: "hii!" as const,
});
})
.step("message", async (context) => {
if (context.scene.step.firstTime || context.text !== "2")
return context.send("2");
console.log(context.scene.state.messageId);
// ^?
});
```
## on
This method allows you to register event handlers for a scene.
```ts
const guessRandomNumberScene = new Scene("guess-random-number")
.params<{ randomNumber: number }>()
.on("message", async (context, next) => {
// This check is needed so the handler does not trigger on firstTime because context will be the same as previous step
if (context.scene.step.firstTime) return next();
return await Promise.all([context.delete(), next()]);
})
.step(["message", "callback_query"], async (context) => {
if (context.scene.step.firstTime)
return context.send("Try to guess a number from 1 to 10");
if (!context.is("message"))
return context.answer("Please write a message with a number");
const number = Number(context.text);
if (
Number.isNaN(number) ||
number !== context.scene.params.randomNumber
)
return; // The handler above will delete the user's message
return Promise.all([
context.send(
format(
`Congratulations! You guessed the number ${bold(
context.scene.params.randomNumber
)}!`
)
),
context.scene.exit(),
]);
});
```
Keep in mind that a handler is registered only for all subsequent steps (or .on handlers) after it is declared.
```ts
new Scene("test")
.on(...) // Called for all steps
.step(...)
.on(...) // Called only after the 2nd step is reached
.step(...)
```
## Storage usage
```ts
import { redisStorage } from "@gramio/storage-redis";
const bot = new Bot(process.env.TOKEN as string)
.extend(
scenes([testScene], {
storage: redisStorage(),
})
)
.command("start", async (context) => {
return context.scene.enter(someScene, {
test: true,
});
});
```
[Read more about storages](/storages/)
## Scene context
### update
`update` is a function that updates the data in the scene and preserves their types.
```ts twoslash
import { Scene } from "@gramio/scenes";
const testScene = new Scene("test")
.step("message", async (context) => {
if (context.scene.step.firstTime) return context.send("First message");
if (!context.text) return context.delete();
return context.scene.update({
message: context.text,
});
})
.step("message", async (context) => {
return context.send(context.scene.state.message);
});
```
### state
`state` is an object that contains all the data that has been "collected" in this scene.
(see the example above)
### params
`params` is an object that contains all the data that was passed to the scene on entry.
```ts twoslash
import { Bot } from "gramio";
import { scenes, Scene } from "@gramio/scenes";
const testScene = new Scene("test")
// here we specify the type of scene parameters
.params<{ test: boolean }>()
.step("message", async (context) => {
return context.send(context.scene.params.test);
});
const bot = new Bot(process.env.TOKEN as string)
.extend(scenes([testScene]))
.command("start", async (context) => {
return context.scene.enter(testScene, {
test: true,
});
});
```
### reenter
`reenter` is a function that allows you to re-enter the scene at the first step, losing [state](#state).
```ts
const testScene = new Scene("test")
.on("message", async (context, next) => {
if (context.text === "/start") return context.scene.reenter();
return next();
})
.step("message", async (context) => {
if (context.scene.step.firstTime) return context.send("Hi!");
return context.send("Bye!");
});
```
### Step context
All information about the current scene step is stored in `context.scene.step`.
#### firstTime
`firstTime` is a flag that indicates whether the current step execution is the first.
```ts
const testScene = new Scene("test").step("message", async (context) => {
if (context.scene.step.firstTime) return context.send("First message");
if (context.text !== "next")
return context.send("Subsequent messages until 'next' is written");
return Promise.all([context.send("Last message"), context.scene.exit()]);
});
```
#### next
`next` is a function that passes control to the next scene step.
```ts
const testScene = new Scene("test").step("message", async (context) => {
if (context.scene.step.firstTime) return context.send("First message");
return context.scene.next();
});
```
#### previous
`previous` is a function that passes control to the previous scene step.
```ts
const testScene = new Scene("test").step("message", async (context) => {
if (context.scene.step.firstTime) return context.send("First message");
return context.scene.previous();
});
```
#### go
`go` is a function that passes control to a specific scene step.
```ts
const testScene = new Scene("test").step("message", async (context) => {
if (context.scene.step.firstTime) return context.send("First message");
return context.scene.go(5);
});
```
#### id
`id` is the identifier of the scene step.
```ts
const testScene = new Scene("test").step("message", async (context) => {
if (context.scene.step.firstTime)
return context.send(`Step ${context.scene.step.id}`);
return context.scene.exit();
});
```
#### previousId
`previousId` is the identifier of the previous scene step.
The id of the last step is saved when calling [#go](#go), [#previous](#previous), [#next](#next).
```ts
const testScene = new Scene("test")
.step("message", async (context) => {
if (context.scene.step.firstTime)
return context.send(
`from step ${context.scene.step.previousId} to step ${context.scene.step.id}`
);
return context.scene.exit();
})
.step("message", async (context) => {
return context.scene.step.go(1);
});
```
## Scenes derives
Sometimes you want to control scenes before the plugin executes scene steps but after the scene is fetched from storage.
By default, the `scenes()` function derives what is needed for the next middlewares if the user is not in a scene.
With `scenesDerives()` you can get it earlier and manage scene data.
```ts twoslash
import { Scene } from "@gramio/scenes";
const testScene = new Scene("test").state<{
simple: string;
example: number[];
}>();
// ---cut---
import { scenes, scenesDerives, type AnyScene } from "@gramio/scenes";
import { Bot } from "gramio";
import { redisStorage } from "@gramio/storage-redis";
const storage = redisStorage();
const scenesList: AnyScene[] = [testScene];
const bot = new Bot(process.env.TOKEN as string)
.extend(
scenesDerives(scenesList, {
withCurrentScene: true,
storage,
})
)
.on("message", (context, next) => {
if (context.text === "/start" && context.scene.current) {
if (context.scene.current.is(testScene)) {
console.log(context.scene.current.state);
// ^?
return context.scene.current.step.previous();
} else return context.scene.current.reenter();
}
return next();
})
.extend(
scenes(scenesList, {
storage,
})
)
.command("start", async (context) => {
return context.scene.enter(testScene, {
test: true,
});
});
```
> [!IMPORTANT]
> The same **storage** and **list of scenes** should be shared across `scenes()` and `scenesDerives()` options.
By default, when registering the `scenes()` plugin, `inMemoryStorage` is used. So if you need to use `scenesDerives()` to manage scenes, you must declare `inMemoryStorage` yourself and explicitly specify it in both `scenesDerives()` and `scenes()` options.
```ts
import { inMemoryStorage } from "@gramio/storage";
const storage = inMemoryStorage(); // Stores in process memory and will be erased on restart
const bot = new Bot(process.env.TOKEN as string)
.extend(scenes([testScene], { storage }))
// ...
.extend(scenesDerives([testScene], { storage }));
```
> [!IMPORTANT]
> Be careful. The first step of the scene should also include the event from which you entered the scene. (For example, if you enter via InlineButton click — `callback_query`)
### step
This function defines a scene step. It is executed only when the current scene step id matches the registered step order.
```ts
const testScene = new Scene("test")
// For a single event
.step("message", async (context) => {
if (context.scene.step.firstTime) return context.send("First message");
return context.scene.exit();
})
// For specific events
.step(["message", "callback_query"], async (context) => {
if (context.scene.step.firstTime)
return context.send("Second message after the user's message");
if (context.is("callback_query"))
return context.answer("You pressed the button");
return context.scene.exit();
})
// For all events
.step((context) => {
console.log(context);
return context.scene.exit();
});
```
> [!NOTE]
> If the user triggers an event that is not registered in the step, it will be ignored by the step (but any event handlers registered for it will still be called).
---
---
url: /files/overview.md
---
# Overview
[`@gramio/files`](https://github.com/gramiojs/files) is built-in GramIO package. You can also use it outside of this framework because it is framework-agnostic.
## Usage
```ts twoslash
// @errors: 2345
import { Bot, MediaInput, MediaUpload, InlineKeyboard } from "gramio";
const bot = new Bot(process.env.BOT_BOT_TOKEN as string)
.on("message", async (ctx) => {
ctx.sendMediaGroup([
MediaInput.document(
await MediaUpload.url(
"https://raw.githubusercontent.com/gramiojs/types/main/README.md"
)
),
MediaInput.document(await MediaUpload.path("./package.json")),
]);
})
.onStart(console.log);
bot.start();
```
## Sending files
There are three ways to send files (photos, stickers, audio, media, etc.):
1. If the file is already stored somewhere on the Telegram servers, you don't need to reupload it: each file object has a file_id field, simply pass this file_id as a parameter instead of uploading. There are no limits for files sent this way.
> [!TIP]
> You may find it useful to use the [media-cache](/ru/plugins/official/media-cache) plugin to cache `file_id` on the framework side.
2. Provide Telegram with an HTTP URL for the file to be sent. Telegram will download and send the file. 5 MB max size for photos and 20 MB max for other types of content.
3. Post the file using multipart/form-data in the usual way that files are uploaded via the browser. 10 MB max size for photos, 50 MB for other files.
### Sending by `file_id`
- It is not possible to change the file type when resending by file_id. I.e. a video can't be sent as a photo, a photo can't be sent as a document, etc.
- It is not possible to resend thumbnails.
- Resending a photo by file_id will send all of its sizes.
- file_id is unique for each individual bot and can't be transferred from one bot to another.
- file_id uniquely identifies a file, but a file can have different valid file_ids even for the same bot.
To send a file by `file_id` with GramIO, you can put it `as is`.
```ts twoslash
import { BotLike, MessageContext } from "gramio";
const fileId = "" as string;
const ctx = {} as InstanceType
[](https://www.npmjs.org/package/@gramio/session)
[](https://jsr.io/@gramio/session)
[](https://jsr.io/@gramio/session)
Session plugin for GramIO.
**Currently not optimized and WIP.**
### Installation
::: code-group
```bash [npm]
npm install @gramio/session
```
```bash [yarn]
yarn add @gramio/session
```
```bash [pnpm]
pnpm add @gramio/session
```
```bash [bun]
bun install @gramio/session
```
:::
## Usage
```ts twoslash
import { Bot } from "gramio";
import { session } from "@gramio/session";
const bot = new Bot(process.env.BOT_TOKEN as string)
.extend(
session({
key: "sessionKey",
initial: () => ({ apple: 1 }),
})
)
.on("message", (context) => {
context.send(`🍏 apple count is ${++context.sessionKey.apple}`);
// ^?
})
.onStart(console.log);
bot.start();
```
You can use this plugin with any storage ([Read more](/storages/index))
### Redis example
[More info](https://github.com/gramiojs/storages/tree/master/packages/redis)
```ts
import { Bot } from "gramio";
import { session } from "@gramio/session";
import { redisStorage } from "@gramio/storage-redis";
const bot = new Bot(process.env.BOT_TOKEN as string)
.extend(
session({
key: "sessionKey",
initial: () => ({ apple: 1 }),
storage: redisStorage(),
})
)
.on("message", (context) => {
context.send(`🍏 apple count is ${++context.sessionKey.apple}`);
})
.onStart(console.log);
bot.start();
```
### TypeScript
To **type** a session data, you need to specify the type as the `ReturnType` of the initial function.
```ts
interface MySessionData {
apple: number;
some?: "maybe-empty";
}
bot.extend(
session({
key: "sessionKey",
initial: (): MySessionData => ({ apple: 1 }),
})
);
```
---
---
url: /awesome.md
---
# Something about GramIO
### Bots
- ...
- Your bot
---
---
url: /storages/index.md
---
# Storages
These are some kind of data stores. Their main use is in plugins (for example, [sessions](/plugins/official/session)).
## Adapters
GramIO has many ready-made adapters, but you can also write your own!
- [In Memory](#in-memory) (`@gramio/storage`)
- [Redis](#redis) (`@gramio/storage-redis`)
## How to write my own storage adapters
It is very simple to write your adapter!
It is enough to return the object with the required methods and use the methods of the solution you have chosen for the adapter. (for example, `ioredis`)
```ts
import type { Storage } from "@gramio/storage";
import ThirdPartyStorage, { type ThirdPartyStorageOptions } from "some-library";
export interface MyOwnStorageOptions extends ThirdPartyStorageOptions {
/** add new property to options */
some?: number;
}
export function myOwnStorage(options: MyOwnStorageOptions = {}): Storage {
const storage = new ThirdPartyStorage(options);
return {
async get(key) {
const data = await storage.get(key);
return data ? JSON.parse(data) : undefined;
},
async has(key) {
return storage.has(key);
},
async set(key, value) {
await storage.set(key, JSON.stringify(value));
},
async delete(key) {
return storage.delete(key);
},
};
}
```
> [!IMPORTANT]
> If you want to publish your adapter, we recommend that you follow the **convention** and name it starting with `gramio-storage` and add `gramio` + `gramio-storage` keywords in your **package.json**
## How to use storage adapters in my own plugin
It is also very easy to work with storage adapters in your plugin!
Everything we need is already in `@gramio/storage`.
```ts
import { Plugin } from "gramio";
import { type Storage, inMemoryStorage } from "@gramio/storage";
export interface MyOwnPluginOptions {
storage?: Storage;
}
export function myOwnPlugin(options: MyOwnPluginOptions = {}) {
// use in memory storage by default
const storage = options.storage ?? inMemoryStorage();
return new Plugin("gramio-example");
}
```
> [!IMPORTANT]
> You can scaffold this example by [create-gramio-plugin](/plugins/how-to-write.html#scaffolding-the-plugin)
## List
## In Memory
[](https://www.npmjs.org/package/@gramio/storage)
[](https://www.npmjs.org/package/@gramio/storage)
[](https://jsr.io/@gramio/storage)
[](https://jsr.io/@gramio/storage)
##### Installation
::: code-group
```bash [npm]
npm install @gramio/storage
```
```bash [yarn]
yarn add @gramio/storage
```
```bash [pnpm]
pnpm add @gramio/storage
```
```bash [bun]
bun install @gramio/storage
```
:::
##### Usage
1. With default [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)
```ts twoslash
import { inMemoryStorage } from "@gramio/storage";
const storage = inMemoryStorage();
```
2. Provide your own [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)
```ts twoslash
import { inMemoryStorage, type InMemoryStorageMap } from "@gramio/storage";
const map: InMemoryStorageMap = new Map();
const storage = inMemoryStorage(map);
```
## Redis
[](https://www.npmjs.org/package/@gramio/storage-redis)
[](https://www.npmjs.org/package/@gramio/storage-redis)
[](https://jsr.io/@gramio/storage-redis)
[](https://jsr.io/@gramio/storage-redis)
##### Installation
::: code-group
```bash [npm]
npm install @gramio/storage-redis
```
```bash [yarn]
yarn add @gramio/storage-redis
```
```bash [pnpm]
pnpm add @gramio/storage-redis
```
```bash [bun]
bun install @gramio/storage-redis
```
:::
##### Usage
1. Provide ioredis options to the `redisStorage` function
```ts twoslash
import { redisStorage } from "@gramio/storage-redis";
const storage = redisStorage({
host: process.env.REDIS_HOST,
});
```
2. Provide ioredis instance to the `redisStorage` function
```ts twoslash
import { redisStorage } from "@gramio/storage-redis";
import { Redis } from "ioredis";
const redis = new Redis({
host: process.env.REDIS_HOST,
});
const storage = redisStorage(redis);
```
##### Tips
- You can set the `DEBUG` env to `ioredis:*` to print debug info:
```bash
DEBUG=ioredis:* npm run start
```
and it will looks like this:
```bash
ioredis:redis write command[::1:6379]: 0 -> get([ '@gramio/scenes:617580375' ]) +187ms
ioredis:redis write command[::1:6379]: 0 -> set([ '@gramio/scenes:617580375', '{"name":"scene-name","state":{},"stepId":0,"previousStepId":0,"firstTime":false}' ]) +1ms
```
- For inspecting which data is stored in Redis, we recommend you to use GUI clients like [AnotherRedisDesktopManager](https://github.com/qishibo/AnotherRedisDesktopManager).
---
---
url: /bot-api.md
---
# Bot API
> [Telegram Bot API documentation](https://core.telegram.org/bots/api)
[Bot API](https://core.telegram.org/bots/api) is a high-level HTTP interface to the Telegram API that makes it easy to develop bots.
Under the hood, [Bot API](https://core.telegram.org/bots/api) uses TDLib (which in turn uses MTProto API).
While the [Bot API](https://core.telegram.org/bots/api) can only be used to work with bot accounts, the MTProto API can be used to work with both bot and user accounts.
If you need to work with MTProto, we recommend you the
mtcute library.
## Calling the Bot API
You can call Telegram Bot API methods via `bot.api` or via the shorthand methods of contexts (for example, `context.send` is `sendMessage` shorthand)
```ts twoslash
import { Bot } from "gramio";
const bot = new Bot("");
// ---cut---
const response = await bot.api.sendMessage({
// ^?
//
//
chat_id: "@gramio_forum",
text: "some text",
});
```
```ts twoslash
import { Bot } from "gramio";
const bot = new Bot("");
// ---cut---
bot.on("message", (context) =>
context.send("This message will be sent to the current chat")
);
```
### Suppressing errors
It can be convenient to handle an error on the spot without using **try/catch** blocks. That's why the `suppress` argument was created, which you can use in **any** API method.
```ts twoslash
import { Bot, TelegramError } from "gramio";
const bot = new Bot("");
// ---cut---
const response = await bot.api.sendMessage({
// ^?
//
//
suppress: true,
chat_id: "@not_found",
text: "Suppressed method",
});
if (response instanceof TelegramError)
console.error("sendMessage returns an error...");
else console.log("Message has been sent successfully");
```
## Handling Rate Limits
Built-in utility for 429 errors:
```ts twoslash
import { Bot } from "gramio";
const bot = new Bot("");
// ---cut---
import { withRetries } from "gramio/utils";
const response = await withRetries(() =>
bot.api.sendMessage({
chat_id: "@gramio_forum",
text: "message text",
})
);
response;
// ^?
```
`withRetries` handles both thrown and returned errors with automatic retry logic.
### Types
GramIO re-exports [@gramio/types](https://www.npmjs.com/package/@gramio/types) (Code-generated and Auto-published Telegram Bot API types).
[Read more](/types/index.html)
```ts twoslash
import type { APIMethodParams, APIMethodReturn } from "gramio";
type SendMessageParams = APIMethodParams<"sendMessage">;
// ^? type SendMessageParams = SendMessageParams
//
type GetMeReturn = APIMethodReturn<"getMe">;
// ^? type GetMeReturn = TelegramUser
//
```
For example you can use it in your custom function.
```ts twoslash
import type { APIMethodParams } from "gramio";
// ---cut---
function myCustomSend(params: APIMethodParams<"sendMessage">) {
params;
// ^?
}
```
#### Types for suppressed method
```ts twoslash
import type {
SuppressedAPIMethodParams,
SuppressedAPIMethodReturn,
} from "gramio";
type SendMessageParams = SuppressedAPIMethodParams<"sendMessage">;
// ^? type SendMessageParams = SendMessageParams
//
type GetMeReturn = SuppressedAPIMethodReturn<"getMe">;
// ^? type GetMeReturn = TelegramUser
//
```
### Debugging
In order to debug which requests GramIO sends, you can set the environment variable to `DEBUG=gramio:api:*`
```bash
npx cross-env DEBUG=gramio:api:* node index.js
```
And you will see something like in the console:
```bash
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
```
also if you use [Bun](https://bun.sh) you can use `BUN_CONFIG_VERBOSE_FETCH` environment variable to log network requests. [Read more](https://bun.sh/docs/runtime/debugger#debugging-network-requests).
```sh
BUN_CONFIG_VERBOSE_FETCH=curl bun src/index.ts
```
And logs will looks like:
```curl
[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 startup optimization: --fetch-preconnect
If you are running your bot with Bun, you can use the CLI flag `--fetch-preconnect=mtcute.
## Вызов Bot API
Вы можете вызывать методы Telegram Bot API через `bot.api` или через сокращенные методы контекстов (например, `context.send` - это сокращение для `sendMessage`)
```ts twoslash
import { Bot } from "gramio";
const bot = new Bot("");
// ---cut---
const response = await bot.api.sendMessage({
// ^?
//
//
chat_id: "@gramio_forum",
text: "текст сообщения",
});
```
```ts twoslash
import { Bot } from "gramio";
const bot = new Bot("");
// ---cut---
bot.on("message", (context) =>
context.send("Это сообщение будет отправлено в текущий чат")
);
```
### Подавление ошибок
Бывает удобно обрабатывать ошибку на месте без использования блоков **try/catch**. Для этого был создан аргумент `suppress`, который можно использовать в **любом** методе API.
```ts twoslash
import { Bot, TelegramError } from "gramio";
const bot = new Bot("");
// ---cut---
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) ошибки, но предоставляет утилиту для их обработки.
```ts twoslash
import { Bot } from "gramio";
const bot = new Bot("");
// ---cut---
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](/ru/rate-limits)
### Типы
GramIO реэкспортирует [@gramio/types](https://www.npmjs.com/package/@gramio/types) (кодо-генерируемые и автоматически публикуемые типы Telegram Bot API).
[Подробнее](/ru/types/index.html)
```ts twoslash
import type { APIMethodParams, APIMethodReturn } from "gramio";
type SendMessageParams = APIMethodParams<"sendMessage">;
// ^? type SendMessageParams = SendMessageParams
//
type GetMeReturn = APIMethodReturn<"getMe">;
// ^? type GetMeReturn = TelegramUser
//
```
Например, вы можете использовать их в вашей собственной функции.
```ts twoslash
import type { APIMethodParams } from "gramio";
// ---cut---
function myCustomSend(params: APIMethodParams<"sendMessage">) {
params;
// ^?
}
```
#### Типы для методов с подавлением ошибок
```ts twoslash
import type {
SuppressedAPIMethodParams,
SuppressedAPIMethodReturn,
} from "gramio";
type SendMessageParams = SuppressedAPIMethodParams<"sendMessage">;
// ^? type SendMessageParams = SendMessageParams
//
type GetMeReturn = SuppressedAPIMethodReturn<"getMe">;
// ^? type GetMeReturn = TelegramUser
//
```
### Отладка
Для отладки запросов, которые отправляет GramIO, вы можете установить переменную окружения `DEBUG=gramio:api:*`
```bash
npx cross-env DEBUG=gramio:api:* node index.js
```
И вы увидите что-то подобное в консоли:
```bash
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](https://bun.sh), вы можете использовать переменную окружения `BUN_CONFIG_VERBOSE_FETCH` для логирования сетевых запросов. [Подробнее](https://bun.sh/docs/runtime/debugger#debugging-network-requests).
```sh
BUN_CONFIG_VERBOSE_FETCH=curl bun src/index.ts
```
И логи будут выглядеть так:
```curl
[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=unjs/untun.
**Untun** — это инструмент для создания туннеля между вашим **локальным** HTTP(s) сервером и внешним миром!
> [!IMPORTANT]
> Примеры запуска с конкретными фреймворками опущены. Смотрите [этот пример](#пример).
### Через API
Этот метод позволяет установить ссылку на наш туннель непосредственно в скрипте.
Установите пакет:
::: code-group
```bash [npm]
npm install untun
```
```bash [yarn]
yarn add untun
```
```bash [pnpm]
pnpm install untun
```
```bash [bun]
bun install untun
```
:::
Запустите туннель и установите вебхук:
```ts
import { startTunnel } from "untun";
const tunnel = await startTunnel({ port: 3000 });
bot.start({
webhook: {
url: await tunnel.getURL(),
},
});
```
### Через CLI
Мы прослушиваем порт `3000` локально. Поэтому открываем туннель следующим образом:
::: code-group
```bash [npm]
npx untun@latest tunnel http://localhost:3000
```
```bash [yarn]
yarn dlx untun@latest tunnel http://localhost:3000
```
```bash [pnpm]
pnpm dlx untun@latest tunnel http://localhost:3000
```
```bash [bun]
bunx untun@latest tunnel http://localhost:3000
```
:::
```bash
◐ Starting cloudflared tunnel to http://localhost:3000
ℹ Waiting for tunnel URL...
✔ Tunnel ready at https://unjs-is-awesome.trycloudflare.com
```
Теперь мы используем эту ссылку при установке вебхука:
```ts
bot.start({
webhook: {
url: "https://unjs-is-awesome.trycloudflare.com",
},
});
```
## Напишите свой собственный обработчик обновлений
```ts
// не существующий фреймворк для примера
import { App } from "some-http-framework";
import { Bot } from "gramio";
const bot = new Bot(process.env.BOT_TOKEN as string).on("message", (context) =>
context.send("Hello!")
);
// init обязателен. Он используется для ленивой загрузки плагинов, а также получает информацию о боте.
await bot.init();
const app = new App().post("/telegram", async (req) => {
// req.body должен быть json эквивалентом TelegramUpdate
await bot.updates.handleUpdate(req.body);
});
app.listen(80);
```
---
---
url: /ru/get-started.md
---
# Начало работы
Создайте нового бота с GramIO за считанные минуты. У вас уже должен быть установлен [Node.js](https://nodejs.org/), [Bun](https://bun.sh/) или [Deno](https://deno.com/).
## Получите токен бота
Сначала создайте бота и получите `токен`. Вы можете сделать это с помощью бота [@BotFather](https://t.me/BotFather).
Отправьте команду `/newbot` и следуйте инструкциям, пока не получите токен вида `110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw`.
## Создание проекта вместе с `create-gramio`
Эта команда поможет вам создать проект с GramIO самым простым способом.
::: code-group
```bash [npm]
npm create gramio@latest ./bot
```
```bash [yarn]
yarn create gramio@latest ./bot
```
```bash [pnpm]
pnpm create gramio@latest ./bot
```
```bash [bun]
bun create gramio@latest ./bot
```
```bash [deno]
TODO:// Deno поддерживается, но не в генераторе проектов
```
:::
#### Поддерживаемые инструменты
- ORM/Query builders
- - [Prisma](https://www.prisma.io/)
- - [Drizzle](https://orm.drizzle.team/)
- Линтеры
- - [Biome](https://biomejs.dev/)
- - [ESLint](https://eslint.org/) с [@antfu/eslint-config](https://github.com/antfu/eslint-config)
- Плагины
- - [Scenes](https://gramio.dev/ru/plugins/official/scenes.html)
- - [Session](https://gramio.dev/ru/plugins/official/session.html)
- - [Autoload](https://gramio.dev/ru/plugins/official/autoload.html)
- - [Prompt](https://gramio.dev/ru/plugins/official/prompt.html)
- - [Auto-retry](https://gramio.dev/ru/plugins/official/auto-retry.html)
- - [Media-cache](https://gramio.dev/ru/plugins/official/media-cache.html)
- - [I18n](https://gramio.dev/ru/plugins/official/i18n.html)
- - [Media-group](https://gramio.dev/ru/plugins/official/media-group.html)
- Другое
- - [Dockerfile](https://www.docker.com/) + [docker-compose.yml](https://docs.docker.com/compose/)
- - [Jobify](https://github.com/kravetsone/jobify) (обертка для [Bullmq](https://docs.bullmq.io/))
- - [Husky](https://typicode.github.io/husky/) (Git-хуки)
- - [Fluent2ts](https://github.com/kravetsone/fluent2ts)
- - [GramIO storages](https://gramio.dev/ru/storages/)
- [Telegram apps](https://github.com/Telegram-Mini-Apps/telegram-apps/tree/master/packages/create-mini-app)
- [Elysia](https://elysiajs.com/) (через [create-elysiajs](https://github.com/kravetsone/create-elysiajs))
> Инструменты могут работать `вместе`
>
> Когда вы выбираете [ESLint](https://eslint.org/) и [Drizzle](https://orm.drizzle.team/), вы получаете [eslint-plugin-drizzle](https://orm.drizzle.team/docs/eslint-plugin)
## Ручная установка
Чтобы вручную создать нового бота с GramIO, установите пакет:
::: code-group
```bash [npm]
npm install gramio
```
```bash [yarn]
yarn add gramio
```
```bash [pnpm]
pnpm add gramio
```
```bash [bun]
bun install gramio
```
:::
Настройте TypeScript:
::: code-group
```bash [npm]
npm install typescript -D
npx tsc --init
```
```bash [yarn]
yarn add typescript -D
yarn dlx tsc --init
```
```bash [pnpm]
pnpm add typescript -D
pnpm exec tsc --init
```
```bash [bun]
bun install typescript -D
bunx tsc --init
```
:::
Создайте папку `src` с файлом `index.ts` и напишите что-то вроде:
::: code-group
```ts twoslash [Bun или Node.js]
import { Bot } from "gramio";
const bot = new Bot("") // укажите ваш токен здесь
.command("start", (context) => context.send("Привет!"))
.onStart(console.log);
bot.start();
```
```ts [Deno]
import { Bot } from "jsr:@gramio/core";
const bot = new Bot("") // укажите ваш токен здесь
.command("start", (context) => context.send("Привет!"))
.onStart(console.log);
bot.start();
```
:::
И запустите бота с помощью:
::: code-group
```bash [tsx]
npx tsx ./src/index.ts
```
```bash [bun]
bun ./src/index.ts
```
```bash [deno]
deno run --allow-net ./src/index.ts
```
:::
Готово! 🎉
Теперь вы можете взаимодействовать со своим ботом Telegram.
---
---
url: /ru/triggers/inline-query.md
---
# inlineQuery
Метод `inlineQuery` в GramIO позволяет вашему боту отвечать на инлайн-запросы, отправленные пользователями. Инлайн-запрос - это особый тип сообщения, когда пользователи могут искать контент от вашего бота, введя запрос в поле ввода сообщения, не взаимодействуя напрямую с ботом.
[Документация Telegram](https://core.telegram.org/bots/inline)
> [!WARNING]
> Вам необходимо включить эту опцию через [@BotFather](https://telegram.me/botfather). Отправьте команду `/setinline`, выберите бота и укажите текст-заполнитель, который пользователь увидит в поле ввода после ввода имени вашего бота.
## Основное использование
### Ответ на инлайн-запрос с использованием регулярного выражения
Вы можете настроить бота на прослушивание определенных инлайн-запросов, соответствующих регулярному выражению, и ответить результатами. Вот пример:
```ts
bot.inlineQuery(/search (.*)/i, async (context) => {
if (context.args) {
await context.answer([
InlineQueryResult.article(
"id-1",
`Результат для ${context.args.at(1)}`,
InputMessageContent.text(
`Это результат сообщения для запроса ${context.args.at(1)}`
)
),
]);
}
});
```
В этом примере:
- Бот прослушивает инлайн-запросы, соответствующие шаблону `search (.*)`.
- Если соответствие найдено, бот извлекает поисковый запрос и возвращает список результатов инлайн-запроса.
### Параметры
- **`trigger`**: Условие, которому должен соответствовать инлайн-запрос. Это может быть регулярное выражение, строка или пользовательская функция.
- **Регулярное выражение**: Соответствует запросам, которые соответствуют определенному шаблону.
- **Строка**: Соответствует точной строке запроса.
- **Функция**: Оценивает запрос на основе пользовательской логики. Должна возвращать true для соответствия.
- **`handler`**: Функция, которая обрабатывает инлайн-запрос. Она получает объект `context`, который включает детали о запросе и предоставляет методы для ответа.
- **`options`**: Дополнительные опции для обработки выбора результата.
- **`onResult`**: Функция, которая вызывается, когда пользователь выбирает результат инлайн-запроса. Она может использоваться для изменения или обновления сообщения после выбора. Использует [ChosenInlineResult](/ru/triggers/chosen-inline-result) под капотом.
> [!IMPORTANT]
> Вы можете изменять только сообщения, которые содержат InlineKeyboard. Подробнее о [ChosenInlineResult](/ru/triggers/chosen-inline-result).
### Как работает `inlineQuery`
1. **Сопоставление запроса**: Когда пользователь вводит инлайн-запрос, метод `inlineQuery` проверяет, соответствует ли запрос предоставленному `trigger`. Это может быть прямое соответствие (строка), соответствие шаблону (регулярное выражение) или проверка условия (функция).
2. **Обработка запроса**: Если запрос соответствует, вызывается функция `handler`. Внутри этой функции вы можете получить доступ к параметрам запроса, сгенерировать результаты и отправить их обратно пользователю, используя `context.answer()`.
3. **Реагирование на выбор результата**: Если предоставлена опция `onResult`, бот прослушивает, когда пользователь выбирает один из результатов инлайн-запроса. Затем предоставленная функция может, например, изменить текст сообщения.
### Пример: Пользовательский обработчик инлайн-запросов
Вот более подробный пример, демонстрирующий использование как триггера инлайн-запроса, так и обработки выбора результата:
```ts
bot.inlineQuery(
/search (.*)/i,
async (context) => {
if (context.args) {
await context.answer(
[
InlineQueryResult.article(
"result-1",
`Результат для ${context.args[1]}`,
InputMessageContent.text(
`Вы искали: ${context.args[1]}`
),
{
reply_markup: new InlineKeyboard().text(
"Получить подробности",
"details-callback"
),
}
),
],
{
cache_time: 0,
}
);
}
},
{
onResult: (context) => context.editText("Вы выбрали результат!"),
}
);
```
В этом примере:
- Бот прослушивает инлайн-запросы, которые начинаются с `search `, за которыми следует поисковый термин.
- Бот отвечает результатом инлайн-запроса, который включает кнопку с надписью "Получить подробности."
- Когда пользователь выбирает этот результат, бот редактирует сообщение, чтобы указать, что был сделан выбор.
---
---
url: /ru/triggers/command.md
---
# Команды
Метод command в GramIO позволяет создавать обработчики для определенных [команд бота](https://core.telegram.org/bots/features#commands). Команды - это определенные слова или фразы, которые обычно начинаются с `/` и используются для вызова действий или ответов от бота.
Приложения Telegram будут:
- **Выделять** команды в сообщениях. Когда пользователь нажимает на выделенную команду, эта команда сразу же отправляется снова.
- Предлагать **список поддерживаемых команд** с описаниями, когда пользователь вводит `/` (для этого вам нужно предоставить список команд [@BotFather](https://t.me/botfather) или через [соответствующий метод API](https://core.telegram.org/bots/api#setmycommands)). Выбор команды из списка сразу отправляет её.
- Показывать [кнопку меню](https://core.telegram.org/bots/features#menu-button), содержащую все или некоторые команды бота (которые вы устанавливаете через [@BotFather](https://t.me/botfather)).
Команды всегда должны начинаться с символа `/` и содержать **до 32 символов**. Они могут использовать **латинские буквы**, **цифры** и **подчеркивания**, хотя для более чистого вида рекомендуется использовать простой текст в нижнем регистре.
> [!IMPORTANT]
> Команда также может быть вызвана с использованием полной команды с именем пользователя бота, например, `/start@name_bot`.
## Основное использование
### Регистрация простой команды
Вы можете использовать метод `command`, чтобы ваш бот отвечал на определенные команды. Вот простой пример:
```ts
bot.command("start", (context) => {
return context.send(`Привет!`);
});
```
> [!IMPORTANT]
> Вам не нужно включать `/` при указании имени команды. Если вы включите его, вы получите `ошибку`.
В этом примере бот прослушивает команду `/start`. Когда команда получена, бот отвечает простым сообщением "Привет!".
### Пример с аргументами команды
Вот пример, демонстрирующий, как использовать аргументы с командами:
```ts
bot.command("start", async (context) => {
return context.send(
`Вы ввели команду /start с аргументами: ${context.args}`
);
});
```
В этом сценарии, если пользователь отправляет `/start arg1 arg2`, бот ответит `Вы ввели команду /start с аргументами: arg1 arg2`.
### Как работает `command`
1. **Распознавание команды:** Бот проверяет сообщение на наличие команды (например, `/start`). Команды обычно обозначаются сущностью [`bot_command`](https://core.telegram.org/bots/api#messageentity) в сообщениях Telegram.
2. **Сопоставление команды:** Бот сравнивает обнаруженную команду с командой, которую вы указали в методе `command`.
3. **Обработка команд с именем пользователя бота:** Команда также распознается, если она включает имя пользователя бота, например, `/start@name_bot`.
4. **Аргументы команды:** Если после команды есть дополнительные аргументы (например, `/start arg1 arg2`), они передаются в `context.args` для дальнейшей обработки.
---
---
url: /ru/updates/overview.md
---
# Обработка обновлений
## Start
Метод `start` запускает процесс получения обновлений от Telegram для вашего бота. В зависимости от переданных параметров, бот может использовать long-polling или webhook для получения событий. Этот метод инициализирует бота, подгружает [lazy плагины](/ru/plugins/lazy-load) и вызывает хук [`onStart`](/ru/hooks/on-start).
**Сигнатура:**
```ts
start(options?): Promise
[](https://www.npmjs.org/package/@gramio/i18n)
[](https://jsr.io/@gramio/i18n)
[](https://jsr.io/@gramio/i18n)
Плагин `i18n` для [GramIO](https://gramio.dev/).
Этот плагин помогает добавить многоязычность в ваши боты с помощью синтаксиса [Fluent](https://projectfluent.org/).
Вы можете настроить [типо-безопасность](#типо-безопасность) для него.
Плагин `i18n` для [GramIO](https://gramio.dev/).
Этот плагин предоставляет удобный способ добавить многоязычность в ваши боты! Его можно использовать без GramIO, но он всегда будет учитывать его особенности.
> [!IMPORTANT]
> Начиная с версии `1.0.0`, у нас есть два способа написания локализации: [`I18n-in-TS`](#синтаксис-i18n-in-ts) и [`Fluent`](#синтаксис-fluent)
### Установка
Для [синтаксиса I18n-in-TS](#синтаксис-i18n-in-ts)
::: code-group
```bash [npm]
npm install @gramio/i18n
```
```bash [bun]
bun add @gramio/i18n
```
```bash [yarn]
yarn add @gramio/i18n
```
```bash [pnpm]
pnpm add @gramio/i18n
```
:::
Для [синтаксиса Fluent](#синтаксис-fluent)
::: code-group
```bash [npm]
npm install @gramio/i18n @fluent/bundle
```
```bash [bun]
bun add @gramio/i18n @fluent/bundle
```
```bash [yarn]
yarn add @gramio/i18n @fluent/bundle
```
```bash [pnpm]
pnpm add @gramio/i18n @fluent/bundle
```
:::
## Синтаксис I18n-in-TS
Этот синтаксис позволяет вам писать локализацию, не выходя из файлов `.ts`, и не требует генерации кода для **типо-безопасности**, а также обеспечивает удобную интеграцию с **Format API** из коробки!
```ts twoslash
import { format, Bot } from "gramio";
import {
defineI18n,
type LanguageMap,
type ShouldFollowLanguage,
} from "@gramio/i18n";
const en = {
greeting: (name: string) => format`Hello, ${name}!`,
and: {
some: {
nested: "Hi!!!",
},
},
} satisfies LanguageMap;
const ru = {
greeting: (name: string) => format`Привет, ${name}!`,
and: {
some: {
nested: "Hi!!!",
},
},
} satisfies ShouldFollowLanguage
[](https://www.npmjs.org/package/@gramio/prompt)
[](https://jsr.io/@gramio/prompt)
[](https://jsr.io/@gramio/prompt)
Плагин, который предоставляет методы [Prompt](#prompt) и [Wait](#wait)
### Установка
::: code-group
```bash [npm]
npm install @gramio/prompt
```
```bash [yarn]
yarn add @gramio/prompt
```
```bash [pnpm]
pnpm add @gramio/prompt
```
```bash [bun]
bun install @gramio/prompt
```
:::
## Использование
```ts
import { Bot, format, bold } from "gramio";
import { prompt } from "@gramio/prompt";
const bot = new Bot(process.env.BOT_TOKEN as string)
.extend(prompt())
.command("start", async (context) => {
const answer = await context.prompt(
"message",
format`Как вас ${bold`зовут`}?`
);
return context.send(`✨ Ваше имя: ${answer.text}`);
})
.onStart(console.log);
bot.start();
```
## Prompt
### Prompt с текстом + параметрами
```ts
const answer = await context.prompt("Как вас зовут?");
// или с SendMessageParams
const answer = await context.prompt("Правда или ложь?", {
reply_markup: new Keyboard().text("правда").row().text("ложь"),
});
```
ответ - это объект `MessageContext` или `CallbackQueryContext`
### Prompt с текстом + параметрами и указанным событием
```ts
const answer = await context.prompt("message", "Как вас зовут?");
const answer = await context.prompt("callback_query", "Правда или ложь?", {
reply_markup: new InlineKeyboard()
.text("правда", "true")
.row()
.text("ложь", "false"),
});
```
ответ - это объект `CallbackQueryContext`
### Валидация
Можно указать обработчик в параметрах для проверки ответа пользователя.
Если обработчик вернёт false, сообщение будет отправлено повторно.
```ts
const answer = await context.prompt(
"message",
"Введите строку, содержащую русскую букву",
{
validate: (context) => /[а-яА-Я]/.test(context.text),
//... и другие SendMessageParams
}
);
```
### Трансформация
```ts
const name = await context.prompt(
"message",
format`Как вас ${bold`зовут`}?`,
{
transform: (context) => context.text || context.caption || "",
}
);
```
name имеет тип `string`
## Wait
### Ожидание следующего события от пользователя
```ts
const answer = await context.wait();
```
ответ - это объект `MessageContext` или `CallbackQueryContext`
### Ожидание события от пользователя с игнорированием других типов событий
```ts
const answer = await context.wait("message");
```
ответ - это объект `CallbackQueryContext`
### Ожидание события с отфильтрованными ответами
Можно указать обработчик в параметрах для проверки ответа пользователя.
Если обработчик вернёт `false`, **сообщение** будет проигнорировано
```ts
const answer = await context.wait((context) => /[а-яА-Я]/.test(context.text));
// или в сочетании с событием
const answer = await context.wait("message", (context) =>
/[а-яА-Я]/.test(context.text)
);
```
### Ожидание события с проверкой и трансформацией ответа
Можно указать обработчик в параметрах для **трансформации** ответа пользователя.
```ts
const answer = await context.wait((context) => /[а-яА-Я]/.test(context.text));
// или в сочетании с событием
const answer = await context.wait("message", {
validate: (context) => /[а-яА-Я]/.test(context.text),
transform: (context) => c.text || "",
});
```
ответ имеет тип `string`
---
---
url: /ru/plugins/official/autoload.md
---
# Плагин автозагрузки
[](https://www.npmjs.org/package/@gramio/autoload)
[](https://jsr.io/@gramio/autoload)
[](https://jsr.io/@gramio/autoload)
Плагин автозагрузки команд для GramIO с поддержкой [`Bun.build`](#использование-bun-build).
### Установка
::: code-group
```bash [npm]
npm install @gramio/autoload
```
```bash [yarn]
yarn add @gramio/autoload
```
```bash [pnpm]
pnpm add @gramio/autoload
```
```bash [bun]
bun install @gramio/autoload
```
:::
## Использование
> [полный пример](https://github.com/gramiojs/autoload/tree/main/example)
> [!IMPORTANT]
> Пожалуйста, прочитайте о [Ленивой загрузке плагинов](https://gramio.dev/ru/plugins/official/autoload.html)
## Регистрация плагина
```ts twoslash
// index.ts
import { Bot } from "gramio";
import { autoload } from "@gramio/autoload";
const bot = new Bot(process.env.BOT_TOKEN as string)
.extend(await autoload())
.onStart(console.log);
bot.start();
export type BotType = typeof bot;
```
## Создание команды
```ts
// commands/command.ts
import type { BotType } from "..";
export default (bot: BotType) =>
bot.command("start", (context) => context.send("привет!"));
```
## Опции
| Ключ | Тип | По умолчанию | Описание |
| ----------------- | -------------------------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------------ |
| pattern? | string \| string[] | "\*\*\/\*.{ts,js,cjs,mjs}" | [Шаблоны Glob](
[](https://www.npmjs.org/package/@gramio/auto-answer-callback-query)
[](https://jsr.io/@gramio/auto-answer-callback-query)
[](https://jsr.io/@gramio/auto-answer-callback-query)
Этот плагин автоматически отвечает на события `callback_query` методом `answerCallbackQuery`, если вы этого еще не сделали.
### Установка
::: code-group
```bash [npm]
npm install @gramio/auto-answer-callback-query
```
```bash [yarn]
yarn add @gramio/auto-answer-callback-query
```
```bash [pnpm]
pnpm add @gramio/auto-answer-callback-query
```
```bash [bun]
bun install @gramio/auto-answer-callback-query
```
:::
```ts
import { Bot, InlineKeyboard } from "gramio";
import { autoAnswerCallbackQuery } from "@gramio/auto-answer-callback-query";
const bot = new Bot(process.env.BOT_TOKEN as string)
.extend(autoAnswerCallbackQuery())
.command("start", (context) =>
context.send("Привет!", {
reply_markup: new InlineKeyboard()
.text("тест", "test")
.text("тест2", "test2"),
})
)
.callbackQuery("test", () => {
// Плагин вызовет метод answerCallbackQuery, так как вы его не вызвали
return context.send("Привет");
})
.callbackQuery("test2", (context) => {
// вы уже ответили, поэтому плагин не будет пытаться ответить
return context.answer("ПРИВЕТ");
});
```
### Параметры
Вы можете передать параметры для метода [answerCallbackQuery](https://core.telegram.org/bots/api#answercallbackquery)
```ts
bot.extend(
autoAnswerCallbackQuery({
text: "Автоматический ответ",
show_alert: true,
})
);
```
> [!IMPORTANT]
> Этот плагин перехватывает методы `context.answerCallbackQuery` (и `context.answer`), чтобы понять, был ли уже отправлен ответ на запрос обратного вызова. Старайтесь не использовать напрямую метод `bot.api.answerCallbackQuery` в контексте - это может помешать корректной работе плагина.
---
---
url: /ru/plugins/official/auto-retry.md
---
# Плагин автоматического повтора
[](https://www.npmjs.org/package/@gramio/auto-retry)
[](https://jsr.io/@gramio/auto-retry)
[](https://jsr.io/@gramio/auto-retry)
Плагин, который ловит ошибки с полем `retry_after` (**ошибки превышения лимита запросов**), **ждёт** указанное время и **повторяет** API-запрос.
### Установка
::: code-group
```bash [npm]
npm install @gramio/auto-retry
```
```bash [yarn]
yarn add @gramio/auto-retry
```
```bash [pnpm]
pnpm add @gramio/auto-retry
```
```bash [bun]
bun install @gramio/auto-retry
```
:::
### Использование
```ts
import { Bot } from "gramio";
import { autoRetry } from "@gramio/auto-retry";
const bot = new Bot(process.env.BOT_TOKEN as string)
.extend(autoRetry())
.command("start", async (context) => {
for (let index = 0; index < 100; index++) {
await context.reply(`сообщение ${index}`);
}
})
.onStart(console.log);
bot.start();
```
---
---
url: /ru/plugins/official/media-cache.md
---
# Плагин кэширования медиа
[](https://www.npmjs.org/package/@gramio/media-cache)
[](https://jsr.io/@gramio/media-cache)
[](https://jsr.io/@gramio/media-cache)
Плагин `Media cache` для [GramIO](https://gramio.dev/).
Этот плагин кэширует отправленные `file_id` и предотвращает повторную загрузку файлов.
На данный момент **sendMediaGroup** не кэшируется.
## Использование
```ts
import { Bot } from "gramio";
import { mediaCache } from "@gramio/media-cache";
const bot = new Bot(process.env.BOT_TOKEN as string)
.extend(mediaCache())
.command("start", async (context) => {
return context.sendDocument(
await MediaUpload.url(
"https://raw.githubusercontent.com/gramiojs/types/main/README.md"
)
);
})
.onStart(console.log);
bot.start();
```
---
---
url: /ru/plugins/official/media-group.md
---
# Плагин медиа-групп
[](https://www.npmjs.org/package/@gramio/media-group)
[](https://jsr.io/@gramio/media-group)
[](https://jsr.io/@gramio/media-group)
Этот плагин собирает `mediaGroup` из сообщений (**1** вложение = **1** сообщение), используя **задержку**, если `mediaGroupId` присутствует в **MessageContext**. Далее плагин передает только **первое** сообщение по цепочке обработчиков с ключом `mediaGroup`, содержащим **массив** всех сообщений этой **mediaGroup** (включая **первое** сообщение).
```ts
import { Bot } from "gramio";
import { mediaGroup } from "@gramio/media-group";
const bot = new Bot(process.env.BOT_TOKEN as string)
.extend(mediaGroup())
.on("message", async (context) => {
if (!context.mediaGroup) return;
return context.send(
`Подпись из первого сообщения - ${context.caption}. Медиа-группа содержит ${context.mediaGroup.length} вложений`
);
})
.onStart(({ info }) => console.log(`✨ Бот ${info.username} запущен!`));
bot.start();
```
### Установка
::: code-group
```bash [npm]
npm install @gramio/media-group
```
```bash [yarn]
yarn add @gramio/media-group
```
```bash [pnpm]
pnpm add @gramio/media-group
```
```bash [bun]
bun install @gramio/media-group
```
:::
### Настройка
Вы можете изменить время задержки в миллисекундах, просто указав его при вызове:
```typescript
const bot = new Bot(process.env.BOT_TOKEN as string)
.extend(mediaGroup(1000)) // ждём 1 секунду сообщений с mediaGroupId (обновляется с каждым новым сообщением)
.on("message", async (context) => {
if (!context.mediaGroup) return;
return context.send(
`Подпись из первого сообщения - ${context.caption}. Медиа-группа содержит ${context.mediaGroup.length} вложений`
);
})
.onStart(({ info }) => console.log(`✨ Бот ${info.username} запущен!`));
bot.start();
```
По умолчанию это `150 мс`.
---
---
url: /ru/plugins/official/session.md
---
# Плагин сессий
[](https://www.npmjs.org/package/@gramio/session)
[](https://jsr.io/@gramio/session)
[](https://jsr.io/@gramio/session)
Плагин сессий для GramIO.
**Пока не оптимизирован и находится в разработке.**
### Установка
::: code-group
```bash [npm]
npm install @gramio/session
```
```bash [yarn]
yarn add @gramio/session
```
```bash [pnpm]
pnpm add @gramio/session
```
```bash [bun]
bun install @gramio/session
```
:::
## Использование
```ts twoslash
import { Bot } from "gramio";
import { session } from "@gramio/session";
const bot = new Bot(process.env.BOT_TOKEN as string)
.extend(
session({
key: "sessionKey",
initial: () => ({ apple: 1 }),
})
)
.on("message", (context) => {
context.send(`🍏 количество яблок: ${++context.sessionKey.apple}`);
// ^?
})
.onStart(console.log);
bot.start();
```
Этот плагин можно использовать с любым хранилищем ([Подробнее](/ru/storages/index))
### Пример с Redis
[Больше информации](https://github.com/gramiojs/storages/tree/master/packages/redis)
```ts
import { Bot } from "gramio";
import { session } from "@gramio/session";
import { redisStorage } from "@gramio/storage-redis";
const bot = new Bot(process.env.BOT_TOKEN as string)
.extend(
session({
key: "sessionKey",
initial: () => ({ apple: 1 }),
storage: redisStorage(),
})
)
.on("message", (context) => {
context.send(`🍏 количество яблок: ${++context.sessionKey.apple}`);
})
.onStart(console.log);
bot.start();
```
### TypeScript
Чтобы **типизировать** данные сессии, укажите тип как `ReturnType` начальной функции.
```ts
interface MySessionData {
apple: number;
some?: "maybe-empty";
}
bot.extend(
session({
key: "sessionKey",
initial: (): MySessionData => ({ apple: 1 }),
})
);
```
---
---
url: /ru/plugins/official/scenes.md
---
# @gramio/scenes
[](https://www.npmjs.org/package/@gramio/scenes)
[](https://jsr.io/@gramio/scenes)
[](https://jsr.io/@gramio/scenes)
API может немного измениться, но мы уже активно используем его на боевых проектах.
# Использование
```ts twoslash
import { Bot } from "gramio";
import { scenes, Scene } from "@gramio/scenes";
export const greetingScene = new Scene("greeting")
.params<{ test: boolean }>()
.step("message", (context) => {
if (context.scene.step.firstTime)
return context.send("Привет! Как тебя зовут?");
if (!context.text) return context.send("Пожалуйста, напиши своё имя");
return context.scene.update({
name: context.text,
});
})
.step("message", (context) => {
if (context.scene.step.firstTime)
return context.send("Сколько тебе лет?");
const age = Number(context.text);
if (!age || Number.isNaN(age) || age < 0)
return context.send("Пожалуйста, укажи возраст корректно");
return context.scene.update({
age,
});
})
.step("message", async (context) => {
await context.send(
`Рад познакомиться! Теперь я знаю, что тебя зовут ${
context.scene.state.name
} и тебе ${context.scene.state.age} лет. ${
context.scene.params.test
? "Также у тебя есть параметр test!"
: ""
}`
);
return context.scene.exit();
});
const bot = new Bot(process.env.TOKEN as string)
.extend(scenes([greetingScene]))
.command("start", async (context) => {
return context.scene.enter(greetingScene, {
test: true,
});
});
```
> [!WARNING]
> Будьте внимательны. Первый шаг сцены должен так же включать в себя событие из которого вы вошли в сцену. (например если по нажатию InlineButton - `callback_query`)
### Общее состояние между шагами
```ts twoslash
import { Scene } from "@gramio/scenes";
const testScene = new Scene("test")
.step("message", async (context) => {
if (context.scene.step.firstTime || context.text !== "1")
return context.send("1");
return context.scene.update({
messageId: context.id,
some: "привет!" as const,
});
})
.step("message", async (context) => {
if (context.scene.step.firstTime || context.text !== "2")
return context.send("2");
console.log(context.scene.state.messageId);
});
```
## Использование хранилища
```ts
import { redisStorage } from "@gramio/storage-redis";
const bot = new Bot(process.env.TOKEN as string)
.extend(
scenes([testScene], {
storage: redisStorage(),
})
)
.command("start", async (context) => {
return context.scene.enter(someScene, {
test: true,
});
});
```
[Подробнее о хранилищах](/ru/storages/)
### step
Это функция — шаг сцены. Он выполняется только когда текущий id шага сцены совпадает с порядком зарегистрированного шага.
```ts
const testScene = new Scene("test")
// Для одного события
.step("message", async (context) => {
if (context.scene.step.firstTime)
return context.send("Первое сообщение");
return context.scene.exit();
})
// Для конкретных событий
.step(["message", "callback_query"], async (context) => {
if (context.scene.step.firstTime)
return context.send(
"Второе сообщение после сообщения пользователя"
);
if (context.is("callback_query"))
return context.answer("Вы нажали на кнопку");
return context.scene.exit();
})
// Для всех событий
.step((context) => {
console.log(context);
return context.scene.exit();
});
```
> [!NOTE]
> Если пользователь создаёт событие, которое не зарегистрировано в шаге, оно будет проигнорировано этим шагом (но зарегистрированные для него обработчики событий будут вызваны).
### on
Этот метод позволяет зарегистрировать обработчик событий для сцены.
```ts
const guessRandomNumberScene = new Scene("guess-random-number")
.params<{ randomNumber: number }>()
.on("message", async (context, next) => {
// Это условие нужно, чтобы обработчик не срабатывал при firstTime так как context будет одинаковым с предыдущим шагом
if (context.scene.step.firstTime) return next();
return await Promise.all([context.delete(), next()]);
})
.step(["message", "callback_query"], async (context) => {
if (context.scene.step.firstTime)
return context.send("Попробуй угадать число от 1 до 10");
if (!context.is("message"))
return context.answer("Пожалуйста, отправьте число сообщением");
const number = Number(context.text);
if (
Number.isNaN(number) ||
number !== context.scene.params.randomNumber
)
return; // Обработчик выше удалит отправленное пользователем сообщение
return Promise.all([
context.send(
format(
`Поздравляю! Ты угадал число ${bold(
context.scene.params.randomNumber
)}!`
)
),
context.scene.exit(),
]);
});
```
Обратите внимание: обработчик применяется только ко всем шагам, объявленным после него (или к следующим .on), а не к предыдущим.
```ts
new Scene("test")
.on(...) // Вызывается для всех шагов
.step(...)
.on(...) // Вызывается только после достижения второго шага
.step(...)
```
## Контекст сцены
### update
`update` - это функция, которая обновляет данные в сцене и при этом сохраняет их типы.
```ts twoslash
import { Scene } from "@gramio/scenes";
const testScene = new Scene("test")
.step("message", async (context) => {
if (context.scene.step.firstTime)
return context.send("Первое сообщение");
if (!context.text) return context.delete();
return context.scene.update({
message: context.text,
});
})
.step("message", async (context) => {
return context.send(context.scene.state.message);
// ^?
});
```
### state
`state` - это объект, который содержит все данные, которые были собраны в этой сцене.
(смотрите пример выше)
### params
`params` - это объект, который содержит все данные, которые были переданы в сцену при её входе.
```ts twoslash
import { Bot } from "gramio";
import { scenes, Scene } from "@gramio/scenes";
const testScene = new Scene("test")
// тут мы указываем тип параметров сцены
.params<{ test: boolean }>()
.step("message", async (context) => {
return context.send(context.scene.params.test);
// ^?
});
const bot = new Bot(process.env.TOKEN as string)
.extend(scenes([testScene]))
.command("start", async (context) => {
return context.scene.enter(testScene, {
test: true,
});
});
```
### reenter
`reenter` - это функция, которая позволяет перезайти в сцену в первый шаг потеряв [state](#state).
```ts
const testScene = new Scene("test")
.on("message", async (context, next) => {
if (context.text === "/start") return context.scene.reenter();
return next();
})
.step("message", async (context) => {
if (context.scene.step.firstTime) return context.send("Привет!");
return context.send("Пока!");
});
```
### Контекст шага
Тут находится вся информация о текущем шаге сцены.
Он хранится в `context.scene.step`.
#### firstTime
`firstTime` - это флаг, который указывает, является ли текущее выполнение шага первым.
```ts
const testScene = new Scene("test").step("message", async (context) => {
if (context.scene.step.firstTime) return context.send("Первое сообщение");
if (context.text !== "следующее")
return context.send(
"Последующие сообщения до того как напишут «следующее»"
);
return Promise.all([
context.send("Последнее сообщение"),
context.scene.exit(),
]);
});
```
#### next
`next` - это функция, которая передаёт управление следующему шагу сцены.
```ts
const testScene = new Scene("test").step("message", async (context) => {
if (context.scene.step.firstTime) return context.send("Первое сообщение");
return context.scene.next();
});
```
#### previous
`previous` - это функция, которая передаёт управление предыдущему шагу сцены.
```ts
const testScene = new Scene("test").step("message", async (context) => {
if (context.scene.step.firstTime) return context.send("Первое сообщение");
return context.scene.previous();
});
```
#### go
`go` - это функция, которая передаёт управление конкретному шагу сцены.
```ts
const testScene = new Scene("test").step("message", async (context) => {
if (context.scene.step.firstTime) return context.send("Первое сообщение");
return context.scene.go(5);
});
```
#### id
`id` - это идентификатор шага сцены.
```ts
const testScene = new Scene("test").step("message", async (context) => {
if (context.scene.step.firstTime)
return context.send(`Шаг ${context.scene.step.id}`);
return context.scene.exit();
});
```
#### previousId
`previousId` - это идентификатор предыдущего шага сцены.
Сохраняется id последнего шага при вызове [#go](#go), [#previous](#previous), [#next](#next).
```ts
const testScene = new Scene("test")
.step("message", async (context) => {
if (context.scene.step.firstTime)
return context.send(
`из шага ${context.scene.step.previousId} в шаг ${context.scene.step.id}`
);
return context.scene.exit();
})
.step("message", async (context) => {
return context.scene.step.go(1);
});
```
## scenesDerives
Иногда нужно управлять сценами до выполнения шагов сцены плагином, но после получения сцены из хранилища.
По умолчанию функция `scenes()` передаёт необходимые данные последующим обработчикам, если пользователь не находится в сцене.
С помощью `scenesDerives()` вы можете получить эти данные раньше и управлять ими.
```ts twoslash
import { Scene } from "@gramio/scenes";
const testScene = new Scene("test").state<{
simple: string;
example: number[];
}>();
// ---cut---
import { scenes, scenesDerives, type AnyScene } from "@gramio/scenes";
import { Bot } from "gramio";
import { redisStorage } from "@gramio/storage-redis";
const storage = redisStorage();
const scenesList: AnyScene[] = [testScene];
const bot = new Bot(process.env.TOKEN as string)
.extend(
scenesDerives(scenesList, {
withCurrentScene: true,
storage,
})
)
.on("message", (context, next) => {
if (context.text === "/start" && context.scene.current) {
if (context.scene.current.is(testScene)) {
console.log(context.scene.current.state);
return context.scene.current.step.previous();
} else return context.scene.current.reenter();
}
return next();
})
.extend(
scenes(scenesList, {
storage,
})
)
.command("start", async (context) => {
return context.scene.enter(testScene, {
test: true,
});
});
```
> [!IMPORTANT]
> Одно и то же **хранилище** и **список сцен** нужно использовать и в `scenes()`, и в опциях `scenesDerives()`.
По умолчанию при регистрации плагина `scenes()` используется `inMemoryStorage`. Поэтому если вам нужно использовать `scenesDerives()` для управления сценами, необходимо явно объявить `inMemoryStorage` и явно указать его в опциях как для `scenesDerives()`, так и для `scenes()`.
```ts
import { inMemoryStorage } from "@gramio/storage";
const storage = inMemoryStorage(); // Хранит в памяти процесса и будет стёрто при перезапуске
const bot = new Bot(process.env.TOKEN as string)
.extend(scenes([testScene], { storage }))
// ...
.extend(scenesDerives([testScene], { storage }));
```
---
---
url: /ru/plugins/index.md
---
# Обзор
Пожалуйста, ознакомьтесь с нашими официальными плагинами:
- [Сцены](/ru/plugins/official/scenes)
- [I18n](/ru/plugins/official/i18n)
- [Автозагрузка](/ru/plugins/official/autoload)
- [Автоответ на callback запросы](/ru/plugins/official/auto-answer-callback-query)
- [Сессия](/ru/plugins/official/session)
- [Авто-повтор](/ru/plugins/official/auto-retry)
- [Кеш медиа](/ru/plugins/official/media-cache)
- [Медиа группы](/ru/plugins/official/media-group)
- [Prompt](/ru/plugins/official/prompt)
---
---
url: /ru/keyboards/inline-keyboard.md
---
# Inline Keyboard
Inline Keyboard прикрепляется к сообщению. Представляет собой [встроенную клавиатуру](https://core.telegram.org/bots/features#inline-keyboards), которая появляется рядом с сообщением, к которому она принадлежит.
Смотрите также [API Reference](https://jsr.io/@gramio/keyboards/doc/~/InlineKeyboard) и [как отвечать на нажатия](/ru/triggers/callback-query).
## Импорт
### С GramIO
```ts twoslash
import { InlineKeyboard } from "gramio";
```
### Без GramIO
```ts twoslash
import { InlineKeyboard } from "@gramio/keyboards";
```
## Кнопки ([Документация](https://core.telegram.org/bots/api/#inlinekeyboardbutton))
Кнопки - это методы, которые собирают inline клавиатуру для вас.
### text
Текстовая кнопка с данными, которые будут отправлены в [callback query](https://core.telegram.org/bots/api/#callbackquery) боту при нажатии кнопки, 1-64 байта.
```ts twoslash
import { InlineKeyboard } from "@gramio/keyboards";
// ---cut---
new InlineKeyboard().text("какой-то текст", "payload");
// или
new InlineKeyboard().text("какой-то текст", {
json: "payload",
}); // использует JSON.stringify
```
### url
HTTP или tg:// URL, который будет открыт при нажатии на кнопку. Ссылки `tg://user?id=
[](https://www.npmjs.org/package/@gramio/storage)
[](https://www.npmjs.org/package/@gramio/storage)
[](https://jsr.io/@gramio/storage)
[](https://jsr.io/@gramio/storage)
##### Установка
::: code-group
```bash [npm]
npm install @gramio/storage
```
```bash [yarn]
yarn add @gramio/storage
```
```bash [pnpm]
pnpm add @gramio/storage
```
```bash [bun]
bun install @gramio/storage
```
:::
##### Использование
1. С использованием стандартного [Map](https://developer.mozilla.org/ru/docs/Web/JavaScript/Reference/Global_Objects/Map)
```ts twoslash
import { inMemoryStorage } from "@gramio/storage";
const storage = inMemoryStorage();
```
2. Предоставление своего собственного [Map](https://developer.mozilla.org/ru/docs/Web/JavaScript/Reference/Global_Objects/Map)
```ts twoslash
import { inMemoryStorage, type InMemoryStorageMap } from "@gramio/storage";
const map: InMemoryStorageMap = new Map();
const storage = inMemoryStorage(map);
```
## Redis
[](https://www.npmjs.org/package/@gramio/storage-redis)
[](https://www.npmjs.org/package/@gramio/storage-redis)
[](https://jsr.io/@gramio/storage-redis)
[](https://jsr.io/@gramio/storage-redis)
##### Установка
::: code-group
```bash [npm]
npm install @gramio/storage-redis
```
```bash [yarn]
yarn add @gramio/storage-redis
```
```bash [pnpm]
pnpm add @gramio/storage-redis
```
```bash [bun]
bun install @gramio/storage-redis
```
:::
##### Использование
1. Предоставление параметров ioredis для функции `redisStorage`
```ts twoslash
import { redisStorage } from "@gramio/storage-redis";
const storage = redisStorage({
host: process.env.REDIS_HOST,
});
```
2. Предоставление экземпляра ioredis для функции `redisStorage`
```ts twoslash
import { redisStorage } from "@gramio/storage-redis";
import { Redis } from "ioredis";
const redis = new Redis({
host: process.env.REDIS_HOST,
});
const storage = redisStorage(redis);
```
##### Советы
- Вы можете установить переменную окружения `DEBUG` в `ioredis:*` для вывода отладочной информации:
```bash
DEBUG=ioredis:* npm run start
```
и это будет выглядеть так:
```bash
ioredis:redis write command[::1:6379]: 0 -> get([ '@gramio/scenes:617580375' ]) +187ms
ioredis:redis write command[::1:6379]: 0 -> set([ '@gramio/scenes:617580375', '{"name":"scene-name","state":{},"stepId":0,"previousStepId":0,"firstTime":false}' ]) +1ms
```
- Для проверки того, какие данные хранятся в Redis, мы рекомендуем использовать графические клиенты, такие как [AnotherRedisDesktopManager](https://github.com/qishibo/AnotherRedisDesktopManager).
---
---
url: /ru/hooks/on-error.md
---
# onError (Обработка ошибок)
Бывает, что в middleware возникают ошибки, и нам нужно их обрабатывать.
Для этого был создан хук `onError`.
```ts twoslash
import { Bot } from "gramio";
const bot = new Bot("");
// ---cut---
bot.on("message", () => {
bot.api.sendMessage({
chat_id: "@not_found",
text: "Чат не существует....",
});
});
bot.onError(({ context, kind, error }) => {
if (context.is("message")) return context.send(`${kind}: ${error.message}`);
});
```
### Добавление хука только для определенных контекстов
```ts
bot.onError("message", ({ context, kind, error }) => {
return context.send(`${kind}: ${error.message}`);
});
// или массив
bot.onError(["message", "message_reaction"], ({ context, kind, error }) => {
return context.send(`${kind}: ${error.message}`);
});
```
## Типы ошибок
### Пользовательские
Вы можете отловить ошибку определенного класса, унаследованного от Error.
```ts twoslash
import { Bot, format, bold } from "gramio";
// ---cut---
export class NoRights extends Error {
needRole: "admin" | "moderator";
constructor(role: "admin" | "moderator") {
super();
this.needRole = role;
}
}
const bot = new Bot(process.env.BOT_TOKEN as string)
.error("NO_RIGHTS", NoRights)
.onError("message", ({ context, kind, error }) => {
if (kind === "NO_RIGHTS")
return context.send(
format`У вас недостаточно прав! Вам нужно иметь роль «${bold(
error.needRole
// ^^^^^^^^
)}».`
);
});
bot.on("message", (context) => {
if (context.text === "ban") throw new NoRights("admin");
});
```
> [!IMPORTANT]
> Мы рекомендуем следовать **соглашению** и называть типы ошибок в формате **SCREAMING_SNAKE_CASE**
### Telegram
Эта ошибка является результатом неудачного запроса к Telegram Bot API.
```ts twoslash
import { Bot } from "gramio";
const bot = new Bot("");
// ---cut---
bot.onError(({ context, kind, error }) => {
if (kind === "TELEGRAM" && error.method === "sendMessage") {
error.params; // это параметры sendMessage
}
});
```
### Unknown
Эта ошибка - любая неизвестная ошибка, будь то ваш класс или просто Error.
```ts twoslash
import { Bot } from "gramio";
const bot = new Bot("");
// ---cut---
bot.onError(({ context, kind, error }) => {
if (kind === "UNKNOWN") {
console.log(error.message);
}
});
```
---
---
url: /ru/hooks/on-response.md
---
# onResponse
Этот хук вызывается `после получения успешного ответа` от Telegram Bot API.
## Параметры
Объект с:
- method - название метода API
- params - параметры метода API
- response - ответ
## Пример
```ts twoslash
import { Bot } from "gramio";
const bot = new Bot(process.env.BOT_TOKEN as string).onResponse((context) => {
console.log("ответ для", context.method, context.response);
});
```
### Добавление хука только для определенных методов API
```ts
bot.onResponse("sendMessage", (context) => {
console.log("ответ для sendMessage", context.response);
});
// или массив
bot.onResponse(["sendMessage", "sendPhoto"], (context) => {
console.log("ответ для", context.method, context.response);
});
```
---
---
url: /ru/hooks/on-response-error.md
---
# onResponseError
Этот хук вызывается `после получения ответа с ошибкой` от Telegram Bot API.
## Параметры
[TelegramError](https://jsr.io/@gramio/core@latest/doc/~/TelegramError)
## Пример
```ts twoslash
import { Bot } from "gramio";
const bot = new Bot(process.env.BOT_TOKEN as string).onResponseError(
(context) => {
console.log("Ошибка для", context.method, context.message);
}
);
```
### Добавление хука только для определенных методов API
```ts
bot.onResponseError("sendMessage", (context) => {
console.log("Ошибка для sendMessage", context.message);
});
// или массив
bot.onResponseError(["sendMessage", "sendPhoto"], (context) => {
console.log("Ошибка для", context.method, context.message);
});
```
---
---
url: /ru/hooks/on-start.md
---
# onStart
Этот хук вызывается при `запуске` бота.
## Параметры
```ts
{
plugins: string[];
info: TelegramUser;
updatesFrom: "webhook" | "long-polling";
}
```
- plugins - массив плагинов
- info - информация об аккаунте бота
- updatesFrom - webhook/polling
## Пример
```ts twoslash
import { Bot } from "gramio";
const bot = new Bot(process.env.BOT_TOKEN as string).onStart(
({ plugins, info, updatesFrom }) => {
console.log(`список плагинов - ${plugins.join(", ")}`);
console.log(`имя пользователя бота @${info.username}`);
console.log(`обновления из ${updatesFrom}`);
}
);
bot.start();
```
---
---
url: /ru/hooks/on-stop.md
---
# onStop
Этот хук вызывается при остановке бота.
## Параметры
```ts
{
plugins: string[];
info: TelegramUser;
}
```
- plugins - массив плагинов
- info - информация об аккаунте бота
## Пример
```ts twoslash
// @noErrors
import { Bot } from "gramio";
const bot = new Bot(process.env.BOT_TOKEN as string).onStop(
({ plugins, info }) => {
console.log(`список плагинов - ${plugins.join(", ")}`);
console.log(`имя пользователя бота @${info.username}`);
}
);
bot.start();
bot.stop();
```
---
---
url: /ru/hooks/pre-request.md
---
# preRequest
Этот хук вызывается `перед отправкой запроса` в Telegram Bot API (позволяет нам влиять на отправляемые параметры).
## Параметры
- method - название метода API
- params - параметры метода API
> [!IMPORTANT]
> Возврат контекста из обработчика хука обязателен!
## Пример
```ts twoslash
import { Bot } from "gramio";
const bot = new Bot(process.env.BOT_TOKEN as string).preRequest((context) => {
if (context.method === "sendMessage") {
context.params.text = "измененные параметры";
}
return context;
});
bot.start();
```
### Добавление хука только для определенных методов API
```ts
bot.preRequest("sendMessage", (context) => {
context.params.text = "измененные параметры";
return context;
});
// или массив
bot.preRequest(["sendMessage", "sendPhoto"], (context) => {
if (context.method === "sendMessage") {
context.params.text = "измененные параметры";
} else context.params.caption = "метод sendPhoto";
return context;
});
```
---
---
url: /ru/hooks/overview.md
---
# Хуки
Система хуков позволяет нам подключаться к жизненному циклу API-запроса/контекста и каким-то образом влиять на него.
Ниже приведены хуки, доступные в GramIO:
- [onStart](/ru/hooks/on-start) - вызывается при запуске бота
- [onStop](/ru/hooks/on-stop) - вызывается при остановке бота
- [onError](/ru/hooks/on-error) - вызывается при возникновении ошибки в контекстах
- [preRequest](/ru/hooks/pre-request) - вызывается перед отправкой запроса в Telegram Bot API (позволяет нам влиять на отправляемые параметры)
- [onResponse](/ru/hooks/on-response) - вызывается при получении ответа на API-запрос (только в случае успеха)
- [onResponseError](/ru/hooks/on-response-error) - вызывается при получении ответа на API-запрос (только в случае ошибки)