Вбудовані та власні клавіатури (вбудовано)

Ваш бот може надсилати низку кнопок, які будуть відображатися під повідомленням або замінювати клавіатуру користувача. Вони називаються вбудовані клавіатури та власні клавіатури відповідно. Якщо ви думаєте, що це заплутано, то так воно і є. Спасибі, Telegram, за цю термінологію, яка перетинається.

Спробуємо трохи прояснити ситуацію:

Термін	Визначення
Вбудована клавіатура	набір кнопок, який відображається під повідомленням у чаті.
Власна клавіатура	набір кнопок, який відображається замість системної клавіатури користувача.
Кнопка вбудованої клавіатури	кнопка у вбудованій клавіатурі, при натисканні якої надсилається невидимий користувачеві запит зворотного виклику; іноді просто називається вбудованою кнопкою.
Кнопка власної клавіатури	кнопка на клавіатурі, при натисканні якої надсилається текстове повідомлення з текстом кнопки; іноді просто називається кнопкою.
InlineKeyboard	клас у grammY для створення вбудованих клавіатур.
Keyboard	клас у grammY для створення власних клавіатур.

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

Неможливо вказати в одному повідомленні власну та вбудовану клавіатуру. Ці дві клавіатури є взаємовиключними. Крім того, надісланий тип розмітки відповіді (reply markup) не можна змінити пізніше під час редагування повідомлення. Наприклад, не можна спочатку надіслати власну клавіатуру разом з повідомленням, а потім відредагувати повідомлення, щоб використати вбудовану клавіатуру.

Вбудовані клавіатури

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

grammY має простий та інтуїтивно зрозумілий спосіб створення вбудованої клавіатури, яку ваш бот може надсилати разом із повідомленням. grammY надає клас під назвою InlineKeyboard.

Кнопки, додані за допомогою виклику switchInline, switchInlineCurrent і switchInlineChosen, запускають inline-запити. Перегляньте розділ про inline-запити для отримання додаткової інформації про те, як вони працюють.

Побудова вбудованої клавіатури

Ви можете побудувати вбудовану клавіатуру, створивши новий екземпляр класу InlineKeyboard, а потім додавши до нього кнопки, які вам потрібні, за допомогою .text() та інших його методів.

Ось приклад:

const inlineKeyboard = new InlineKeyboard()
  .text("« 1", "first")
  .text("‹ 3", "prev")
  .text("· 4 ·", "stay")
  .text("5 ›", "next")
  .text("31 »", "last");

Викличте .row(), якщо ви хочете почати новий ряд кнопок. Ви також можете використовувати інші методи, як-от .url(), щоб дозволити клієнту користувача відкрити певну URL-адресу або зробити інші круті речі. Обовʼязково перегляньте всі методи класу InlineKeyboard.

Якщо у вас вже є масив рядків, який ви хочете перетворити на вбудовану клавіатуру, ви можете використати другий, альтернативний стиль для створення екземплярів вбудованої клавіатури. Клас InlineKeyboard має статичні методи, як-от InlineKeyboard.text, які дозволяють створювати обʼєкти кнопок. У свою чергу, ви можете створити екземпляр вбудованої клавіатури з масиву обʼєктів кнопок за допомогою методу InlineKeyboard.from.

Отже, ви можете побудувати вищезгадану вбудовану клавіатуру у функціональний спосіб.

const labelDataPairs = [
  ["« 1", "first"],
  ["‹ 3", "prev"],
  ["· 4 ·", "stay"],
  ["5 ›", "next"],
  ["31 »", "last"],
];
const buttonRow = labelDataPairs
  .map(([label, data]) => InlineKeyboard.text(label, data));
const keyboard = InlineKeyboard.from([buttonRow]);

Надсилання вбудованої клавіатури

Ви можете надіслати вбудовану клавіатуру безпосередньо разом з повідомленням, незалежно від того, який метод ви використовуєте: bot.api.sendMessage, ctx.api.sendMessage чи ctx.reply:

// Надсилаємо вбудовану клавіатуру разом з повідомленням.
await ctx.reply(text, {
  reply_markup: inlineKeyboard,
});

Звичайно, всі інші методи, які надсилають повідомлення, підтримують ті ж опції, як зазначено у довідці Telegram Bot API. Наприклад, ви можете відредагувати клавіатуру, викликавши editMessageReplyMarkup і передавши новий екземпляр InlineKeyboard як reply_markup. Вкажіть порожню вбудовану клавіатуру, щоб прибрати всі кнопки під повідомленням.

Відповідь на натискання вбудованих клавіатур

Плагін меню

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

До кожної кнопки text додається рядок даних для зворотного виклику. Якщо ви не додасте дані зворотного виклику, grammY буде використовувати текст кнопки як дані.

Щойно користувач натисне кнопку text, ваш бот отримає оновлення з даними зворотного виклику відповідної кнопки. Ви можете обробляти дані зворотного виклику за допомогою bot.callbackQuery().

// Будуємо клавіатуру.
const inlineKeyboard = new InlineKeyboard().text("Натиснути", "click-payload");

// Надсилаємо клавіатуру разом із повідомленням.
bot.command("start", async (ctx) => {
  await ctx.reply("Цікаво? Натисни на мене!", { reply_markup: inlineKeyboard });
});

// Чекаємо на події натискання з певними даними зворотного виклику.
bot.callbackQuery("click-payload", async (ctx) => {
  await ctx.answerCallbackQuery({
    text: "Вам дійсно було цікаво!",
  });
});

Відповідь на всі запити зворотного виклику

bot.callbackQuery() корисний для оброблення подій натискання певних кнопок. Ви можете використовувати bot.on("callback_query:data") для оброблення подій будь-якої кнопки.

bot.callbackQuery("click-payload" /* , ... */);

bot.on("callback_query:data", async (ctx) => {
  console.log("Невідома подія кнопки з даними", ctx.callbackQuery.data);
  await ctx.answerCallbackQuery(); // прибираємо анімацію завантаження
});

Має сенс визначити bot.on("callback_query:data") останнім, щоб завжди відповідати на всі інші запити зворотного виклику, які не були оброблені вашими попередніми обробниками. Інакше деякі клієнти можуть показувати анімацію завантаження до хвилини, коли користувач натискає кнопку, на яку ваш бот не хоче реагувати.

Власні клавіатури

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

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

grammY має простий та інтуїтивно зрозумілий спосіб створення власних клавіатур, якими ваш бот може замінити системну клавіатуру. grammY надає клас під назвою Keyboard.

Як тільки користувач натисне кнопку text, ваш бот отримає надісланий текст у вигляді звичайного текстового повідомлення. Памʼятайте, що ви можете обробляти текстові повідомлення за допомогою bot.on("message:text") або bot.hears().

Побудова власної клавіатури

Ви можете побудувати власну клавіатуру, створивши новий екземпляр класу Keyboard, а потім додавши до нього кнопки за допомогою .text() тощо. Викличте .row(), щоб почати новий ряд кнопок.

Ось приклад:

const keyboard = new Keyboard()
  .text("Yes, they certainly are").row()
  .text("I'm not quite sure").row()
  .text("No. 😈")
  .resized();

Ви також можете надсилати більш потужні кнопки, які запитують номер телефону або місцезнаходження користувача або роблять інші круті речі. Обовʼязково перегляньте всі методи класу Keyboard.

Якщо у вас вже є масив рядків, який ви хочете перетворити на клавіатуру, ви можете використати другий, альтернативний стиль для створення екземплярів власної клавіатури. Клас Keyboard має статичні методи, як-от Keyboard.text, які дозволяють створювати обʼєкти кнопок. У свою чергу, ви можете створити екземпляр класної клавіатури з масиву об’єктів кнопок за допомогою методу Keyboard.from.

Отже, ви можете побудувати вищезгадану власну клавіатуру у функціональний спосіб.

const labels = [
  "Yes, they certainly are",
  "I'm not quite sure",
  "No. 😈",
];
const buttonRows = labels
  .map((label) => [Keyboard.text(label)]);
const keyboard = Keyboard.from(buttonRows).resized();

Надсилання власної клавіатури

Ви можете надіслати власну клавіатуру безпосередньо разом з повідомленням, незалежно від того, який метод ви використовуєте: bot.api.sendMessage, ctx.api.sendMessage чи ctx.reply:

// Надсилаємо клавіатуру з повідомленням.
await ctx.reply(text, {
  reply_markup: keyboard,
});

Звичайно, всі інші методи, які надсилають повідомлення, підтримують ті ж опції, як зазначено у довідці Telegram Bot API.

Ви також можете надати клавіатурі одну або декілька додаткових властивостей, викликавши на ній спеціальні методи. Вони не додаватимуть жодних кнопок, а лише визначатимуть поведінку клавіатури. Ми вже бачили resized у вищенаведеному прикладі - ось ще кілька речей, які ви можете зробити.

Постійні клавіатури

Загалом користувачі бачать іконку, яка дозволяє їм показувати або приховувати власну клавіатуру, встановлену вашим ботом.

Якщо ви хочете, щоб власна клавіатура завжди показувалася, коли звичайна системна клавіатура прихована, ви можете викликати persistent. Отже, користувачі завжди бачитимуть або власну, або системну клавіатуру.

new Keyboard()
  .text("Пропустити")
  .persistent();

Зміна розміру власної клавіатури

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

new Keyboard()
  .text("Так").row()
  .text("Ні")
  .resized();

Не має значення, чи викликаєте ви resized першим, останнім або десь посередині. Результат завжди буде однаковим.

Одноразові власні клавіатури

Ви можете викликати oneTime, якщо хочете, щоб власна клавіатура була прихована одразу після першого натискання кнопки.

new Keyboard()
  .text("Так").row()
  .text("Ні")
  .oneTime();

Не має значення, чи викликаєте ви oneTime першим, останнім або десь посередині. Результат завжди буде однаковим.

Підказка для поля введення

Ви можете викликати placeholder, якщо ви хочете, щоб у полі введення відображався певний текст, поки власна клавіатура є видимою.

new Keyboard()
  .text("Так").row()
  .text("Ні")
  .placeholder("Вирішуй зараз!");

Не має значення, чи викликаєте ви placeholder першим, останнім або десь посередині. Результат завжди буде однаковим.

Вибіркове надсилання власних клавіатур

Ви можете викликати selected, якщо хочете показати власну клавіатуру лише тим користувачам, яких згадано через знак @ у тексті обʼєкта повідомлення, а також відправнику оригінального повідомлення, якщо ваше повідомлення це відповідь.

new Keyboard()
  .text("Так").row()
  .text("Ні")
  .selected();

Не має значення, чи викликаєте ви selected першим, останнім або десь посередині. Результат завжди буде однаковим.

Відповідь на натискання власних клавіатур

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

Ба більше, кнопки завжди надсилають саме те повідомлення, яке на них написано. Telegram не дозволяє створювати кнопки, які відображають один текст, але надсилають інший. Якщо вам потрібно це зробити, використовуйте вбудовану клавіатуру.

Для обробки натискання певної кнопки ви можете використовувати bot.hears з тим самим текстом, який ви розмістили на кнопці. Якщо ви хочете обробити всі натискання кнопок в одному обробнику, використовуйте bot.on("message:text") і перевіряйте ctx.msg.text, щоб визначити, чи була натиснута якась кнопка, чи це звичайне текстове повідомлення.

Видалення власної клавіатури

Якщо не вказати one_time_keyboard, як описано вище, власна клавіатура залишатиметься відкритою для користувача, але користувач може згорнути її.

Ви можете видалити власну клавіатуру лише під час надсилання нового повідомлення у чаті, так само як ви можете вказати нову клавіатуру лише під час надсилання повідомлення. Передайте { remove_keyboard: true } як reply_markup ось так:

await ctx.reply(text, {
  reply_markup: { remove_keyboard: true },
});

Поруч із параметром remove_keyboard ви можете встановити значення selective: true, щоб вилучити власну клавіатуру лише для вибраних користувачів. Це працює аналогічно вибірковому надсиланню власної клавіатури.

Загальні відомості про плагін

Цей плагін вбудовано в ядро grammY. Вам не потрібно нічого встановлювати, щоб використовувати його. Просто імпортуйте все з самого grammY.

До того ж документація і довідка API цього плагіна уніфіковані з ядром пакета.