Команды

Метод command в GramIO позволяет создавать обработчики для определенных команд бота. Команды - это определенные слова или фразы, которые обычно начинаются с / и используются для вызова действий или ответов от бота.

Приложения Telegram будут:

• Выделять команды в сообщениях. Когда пользователь нажимает на выделенную команду, эта команда сразу же отправляется снова.
• Предлагать список поддерживаемых команд с описаниями, когда пользователь вводит / (для этого вам нужно предоставить список команд @BotFather или через соответствующий метод API). Выбор команды из списка сразу отправляет её.
• Показывать кнопку меню, содержащую все или некоторые команды бота (которые вы устанавливаете через @BotFather).

Команды всегда должны начинаться с символа / и содержать до 32 символов. Они могут использовать латинские буквы, цифры и подчеркивания, хотя для более чистого вида рекомендуется использовать простой текст в нижнем регистре.

IMPORTANT

Команда также может быть вызвана с использованием полной команды с именем пользователя бота, например, /start@name_bot.

Основное использование

Регистрация простой команды

Вы можете использовать метод command, чтобы ваш бот отвечал на определенные команды. Вот простой пример:

bot.command("start", (context) => {
    return context.send(`Привет!`);
});

IMPORTANT

Вам не нужно включать / при указании имени команды. Если вы включите его, вы получите ошибку.

В этом примере бот прослушивает команду /start. Когда команда получена, бот отвечает простым сообщением "Привет!".

Пример с аргументами команды

Вот пример, демонстрирующий, как использовать аргументы с командами:

bot.command("start", async (context) => {
    return context.send(
        `Вы ввели команду /start с аргументами: ${context.args}`
    );
});

В этом сценарии, если пользователь отправляет /start arg1 arg2, бот ответит Вы ввели команду /start с аргументами: arg1 arg2.

Как работает command

1. Распознавание команды: Бот проверяет сообщение на наличие команды (например, /start). Команды обычно обозначаются сущностью bot_command в сообщениях Telegram.

2. Сопоставление команды: Бот сравнивает обнаруженную команду с командой, которую вы указали в методе command.

3. Обработка команд с именем пользователя бота: Команда также распознается, если она включает имя пользователя бота, например, /start@name_bot.

4. Аргументы команды: Если после команды есть дополнительные аргументы (например, /start arg1 arg2), они передаются в context.args для дальнейшей обработки.

Метаданные команд и bot.syncCommands()

Начиная с gramio v0.9, bot.command() принимает опциональный объект CommandMeta между именем команды и хэндлером. Метаданные собираются на этапе регистрации и одним вызовом bot.syncCommands() отправляются в Telegram — больше не нужно вручную дёргать setMyCommands или собирать меню в BotFather.

const bot = new Bot(process.env.BOT_TOKEN!)
    .command("start", { description: "Запустить бота" }, (ctx) => ctx.send("Привет!"))
    .command(
        "help",
        {
            description: "Show help",
            locales: { ru: "Помощь", uk: "Допомога" },
        },
        (ctx) => ctx.send("Помощь!"),
    )
    .command(
        "admin",
        {
            description: "Админ-панель",
            scopes: [{ type: "chat_administrators" }],
        },
        adminHandler,
    )
    .command("debug", { hide: true }, debugHandler);

bot.onStart(() => bot.syncCommands());
await bot.start();

Поля CommandMeta

Поле	Тип	Описание
description	string	Что показывает Telegram в меню команд. Обязательно, чтобы команда попала в меню.
locales	Record<string, string>	Описания по языкам. Ключи — language_code из Telegram. Удобно тащить через localesFor() из @gramio/i18n прямо из файлов переводов.
scopes	BotCommandScope[]	Ограничить видимость команды конкретными контекстами — default, all_private_chats, all_group_chats, all_chat_administrators, chat, chat_administrators, chat_member.
hide	boolean	Не выводить эту команду в меню. Полезно для debug/служебных команд, которые хочется ловить через /, но не показывать пользователям.

Как работает syncCommands()

bot.syncCommands() группирует команды по scope, считает хэш на каждый scope и вызывает setMyCommands только для тех scope, у которых хэш изменился с прошлого запуска. Поэтому дёргать его в onStart дёшево — неизменённые метаданные не жгут лимиты. { exclude: ["debug"] } исключает отдельные команды на этапе синка.

Обычная двухаргументная форма bot.command(name, handler) тоже работает — для команд, которые не должны попадать в меню.