Стилізація кнопок клавіатури в Telegram

Для Telegram-ботів можна налаштовувати колір кнопок клавіатури. Це дозволяє візуально виділити важливі дії та покращити UX сценаріїв.

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

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

• Виділити головну дію (наприклад, «Записатися»)
• Позначити негативні або деструктивні дії (наприклад, «Скасувати»)
• Підкреслити успішне завершення (наприклад, «Підтвердити»)

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

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

Доступні кольори

Telegram підтримує три стилі кнопок:

Область застосування

• Канал: тільки Telegram
• Типи клавіатури: інлайн-клавіатура та звичайна (reply) клавіатура
• Widget та Viber: стилі кнопок не підтримуються

Формат JSON конфігурації

Стиль кнопки задається в полі json кнопки через об'єкт telegram.style.

Мінімальний приклад

Кнопка з синім стилем (primary):

{
  "telegram": {
    "style": "primary"
  }
}

Комбінація з іншими параметрами

Стиль можна комбінувати з іншими налаштуваннями кнопки:

Кнопка-посилання зі зеленим стилем:

{
  "ActionType": "open-url",
  "ActionBody": "https://example.com/booking",
  "telegram": {
    "style": "success"
  }
}

Кнопка переходу з червоним стилем (для скасування):

{
  "ActionType": "reply",
  "ActionBody": "Скасувати",
  "telegram": {
    "style": "danger"
  }
}

Кілька стилів у одному блоці повідомлень:

Кожна кнопка має своє поле json. Наприклад, три кнопки з різними стилями:

• Кнопка 1 — {"telegram": {"style": "primary"}}
• Кнопка 2 — {"telegram": {"style": "success"}}
• Кнопка 3 — {"telegram": {"style": "danger"}}

Допустимі значення

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

Як налаштувати в Scenario Builder

1. Відкрийте блок «Повідомлення з клавіатурою» або інший блок з кнопками.
2. У розділі кожної кнопки знайдіть поле Стиль.
3. Оберіть потрібний стиль із випадаючого списку: Primary, Success або Danger.
4. Зміни збережуться автоматично в JSON конфігурації кнопки.

Стиль зберігається в полі json кнопки у форматі {"telegram": {"style": "..."}}.

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

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

При використанні стилізації кнопок у Telegram важливо:

1. Перевірити канал — стилі працюють тільки для Telegram
2. Використовувати семантику — primary для головних дій, danger для скасування
3. Не перевантажувати — занадто багато кольорових кнопок зменшує читабельність

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

Помилка: Кнопка не змінює колір
Проблема: Канал не Telegram або неправильний формат JSON
Рішення: Перевірити, що сценарій відправляється в Telegram, і що telegram.style містить одне з дозволених значень

Помилка: Стиль ігнорується на старих клієнтах
Проблема: Дуже старі версії Telegram можуть не підтримувати стилі
Рішення: У таких випадках кнопка відображається зі стандартним виглядом

Обмеження

• Стилі працюють тільки для каналу Telegram
• Дозволено тільки три стилі: primary, success, danger
• Widget та Viber не підтримують стилізацію кнопок

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

• Explanation: Про інлайн-клавіатуру в Telegram та Widget — типи дій кнопок та налаштування
• Explanation: Стилізація клавіатури у Viber — аналогічна можливість для Viber
• Explanation: Telegram Web App — використання веб-додатків у Telegram