Команди

Команди — це спеціальні сутності в повідомленнях 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 підтримує надсилання цільових команд ботам, тобто команд, які закінчуються на @your_bot_name. grammY обробляє це автоматично за вас, тому bot.command("start") оброблятиме повідомлення з /start або /start@your_bot_name як команди. Ви можете обробляти лише цільові команди, вказавши bot.command("start@your_bot_name").

Пропонуйте команди користувачам

Ви можете викликати

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

Перегляньте розділ про deep linking у можливостях ботів Telegram, створений командою Telegram.

Коли користувач відвідує https://t.me/your_bot_name?start=payload, його клієнт Telegram покаже кнопку СТАРТ, яка при натисканні надсилає текст із параметра URL-адреси разом із повідомленням: у цьому прикладі текст повідомлення буде "/start payload". Клієнти Telegram не відображатимуть ці дані (payload) для користувача: вони бачитимуть лише "/start" в інтерфейсі користувача, однак ваш бот їх отримає. grammY розпізнає ці дані і надасть доступ до них в ctx.match. У нашому прикладі з наведеним вище посиланням ctx.match міститиме текст "payload".

Deep linking корисний, якщо ви хочете створити реферальну систему або відстежувати, звідки користувачі дізналися про вашого бота. Наприклад, ваш бот може надіслати допис каналу з вбудованою клавіатурою. Кнопка містить URL-адресу, подібну до наведеної вище: наприклад, https://t.me/your_bot_name?start=awesome-channel-post-12345. Коли користувач натискає кнопку під дописом, його клієнт Telegram відкриє чат із вашим ботом і відобразить кнопку СТАРТ, як описано вище. Таким чином ваш бот може визначити, звідки прийшов користувач, і що він натиснув кнопку під певним дописом на каналі.

Ви також можете вставляти такі посилання де завгодно: в Інтернеті, у повідомленнях, у QR-кодах тощо.

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