Команды

Команды — это специальные объекты в сообщениях Telegram, которые служат инструкциями для ботов.

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

Пересмотрите раздел “Команды” в статье Функции Telegram Ботов, написанной командой Telegram.

В grammY предусмотрена специальная обработка команд (например, /start и /help). Вы можете напрямую зарегистрировать слушатели для определенных команд через bot.command().

// Ответить на команду /start.
bot.command("start" /* , ... */);
// Ответить на команду /help.
bot.command("help" /* , ... */);
// Ответить на команды /a, /b, /c, и /d.
bot.command(["a", "b", "c", "d"] /* , ... */);

Обратите внимание, что обрабатываются только те команды, которые находятся в начале сообщения, поэтому если пользователь отправит "Пожалуйста, не отправляйте /start этому боту!", то ваш слушатель не будет вызван, даже если команда /start содержится в сообщении.

Telegram поддерживает отправку целевых команд ботам, то есть команд, которые заканчиваются на @имя_вашего_бота. grammY делает это автоматически, поэтому bot.command("start") будет соответствовать сообщениям с /start и с /start@имя_вашего_бота в качестве команд. Вы можете выбрать соответствие только целевым командам, указав bot.command("start@имя_вашего_бота").

Предлагать команды пользователям

Вы можете вызвать

await bot.api.setMyCommands([
  { command: "start", description: "Запустить бота" },
  { command: "help", description: "Показать текст для справки" },
  { command: "settings", description: "Открыть настройки" },
]);

чтобы клиенты Telegram отображали список предлагаемых команд в поле ввода текста.

Также вы можете настроить это, обратившись к @BotFather.

Аргументы

Пользователи могут отправлять аргументы вместе со своими командами. Вы можете получить доступ к строке аргументов через ctx.match.

bot.command("add", async (ctx) => {
  // `item` будет "яблочный пирог" если пользователь отправит "/add яблочный пирог".
  const item = ctx.match;
});

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

Поддержка Deep Linking

Пересмотрите раздел о глубокой перелинковке в статье Функции Telegram Ботов, написанной командой Telegram.

Когда пользователь заходит на https://t.me/имя_вашего_бота?start=payload, его Telegram-клиент покажет кнопку ЗАПУСТИТЬ, которая (при нажатии) отправит строку из URL-параметра вместе с сообщением, в данном примере текст сообщения будет "/start payload". Клиенты Telegram не покажет payload пользователю (он увидит только "/start" в пользовательском интерфейсе), однако ваш бот получит его. grammY извлекает этот payload для вас и предоставляет её в ctx.match. В нашем примере с приведенной выше ссылкой ctx.match будет содержать строку "payload".

Deep Linking полезен, если вы хотите построить реферальную систему или отследить, где пользователи обнаружили вашего бота. Например, ваш бот может отправить сообщение на канал с кнопкой встроенной клавиатуры. Кнопка содержит URL-адрес, как показано выше, например https://t.me/имя_вашего_бота?start=замечательный-пост-канала-12345. Когда пользователь нажмет на кнопку под постом, его клиент Telegram откроет чат с вашим ботом и отобразит кнопку ЗАПУСТИТЬ, как описано выше. Таким образом, ваш бот сможет определить, откуда пришел пользователь, и что он нажал на кнопку под постом конкретного канала.

Естественно, вы можете встраивать такие ссылки куда угодно: в интернет, в сообщения, в QR-коды и т.д.

Посмотрите этот раздел документации Telegram, чтобы увидеть полный список возможных форматов ссылок. Кроме того, они позволяют предложить пользователям добавить вашего бота в группы или каналы, а также по желанию предоставить ему необходимые права администратора.