Про інлайн-клавіатуру в Telegram та Widget

Інлайн-клавіатура дозволяє відображати кнопки безпосередньо під повідомленням у Telegram та Widget. На відміну від звичайної клавіатури, інлайн-кнопки не займають місце в постійній клавіатурі користувача та дозволяють більш гнучку взаємодію.

Контекст і проблема

У багатьох сценаріях потрібно надати користувачу можливість вибору дії без введення тексту:

Перехід на сайт
Відповідь на питання одним кліком
Навігація по меню
Швидкі дії

Інлайн-клавіатура вирішує цю задачу, дозволяючи додавати кнопки безпосередньо до повідомлення.

Основні концепції

Відмінності від звичайної клавіатури

Інлайн-клавіатура:

Відображається безпосередньо під повідомленням
Не займає місце в постійній клавіатурі
Може містити посилання та спеціальні дії
Працює тільки для Telegram та Widget

Звичайна клавіатура:

Замінює стандартну клавіатуру користувача
Займає весь простір клавіатури
Обмежена текстовими відповідями
Працює для всіх каналів

Типи дій кнопок

Інлайн-клавіатура підтримує різні типи дій через параметр ActionType:

reply — відправка тексту відповіді (за замовчуванням)
open-url — відкриття посилання
none — кнопка без дії

Варіанти підходів

Інлайн-клавіатура vs звичайна клавіатура

Інлайн-клавіатура:

✅ Плюси: Не займає місце в клавіатурі, підтримує посилання, більш гнучка
❌ Мінуси: Працює тільки для Telegram та Widget

Звичайна клавіатура:

✅ Плюси: Працює для всіх каналів, завжди видима
❌ Мінуси: Займає весь простір клавіатури, обмежена текстовими відповідями

Чому використовуємо інлайн-клавіатуру: Для Telegram та Widget інлайн-клавіатура надає більше можливостей та не займає постійний простір клавіатури, що робить інтерфейс більш зручним.

Прийняті рішення

Обмежена підтримка каналів

Інлайн-клавіатура працює тільки для Telegram та Widget через обмеження API інших каналів. Для Viber та Facebook Messenger потрібно використовувати звичайну клавіатуру.

Обов'язковий протокол для посилань

Посилання в ActionBody повинні мати протокол https:// або http://. Це вимога Telegram API для безпеки.

Поп-ап підтвердження для посилань

При кліку на кнопку з посиланням (ActionType: "open-url") відкривається поп-ап з запитанням чи відкрити посилання та назвою сайту. Це забезпечує безпеку користувача.

Наслідки для користувачів і імплементації

Для інтеграторів

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

Перевірити канал — інлайн-клавіатура працює тільки для Telegram та Widget
Включити опцію — обов'язково відмітити чекбокс "Інлайн-клавіатура (тільки Telegram та віджет)"
Налаштувати ActionType — вказати тип дії для кожної кнопки
Додати протокол до посилань — посилання повинні мати протокол https:// або http://

Типові помилки

Помилка: Інлайн-клавіатура не відображається
Проблема: Не відмічено чекбокс "Інлайн-клавіатура"
Рішення: Включити опцію інлайн-клавіатури в налаштуваннях блоку

Помилка: Посилання не працює
Проблема: Посилання не має протоколу або неправильний ActionType
Рішення: Додати протокол https:// та вказати ActionType: "open-url"

Помилка: Кнопка не відправляє відповідь
Проблема: Не вказано ActionBody або неправильний ActionType
Рішення: Вказати ActionType: "reply" та текст у ActionBody

Обмеження

Інлайн-клавіатура працює тільки для Telegram та Widget
Максимальна кількість кнопок в рядку: 8 (для Telegram)
Максимальна кількість рядків: залежить від каналу
Посилання повинні мати протокол https:// або http://

Приклади використання

Кнопка з переходом на сайт

{
  "ActionType": "open-url",
  "ActionBody": "https://example.com"
}

Кнопка з відповіддю

{
  "ActionType": "reply",
  "ActionBody": "Так, згоден"
}

Або можна не вказувати ActionType, тоді буде використано reply за замовчуванням.

Пов'язані документи

Reference: Telegram Bot API - Inline Keyboard — офіційна документація Telegram про інлайн-клавіатури
Explanation: Telegram WebApp — використання WebApp через інлайн-клавіатуру