# Як налаштувати постійну клавіатуру Telegram?

Постійна клавіатура — це кнопки під полем вводу в Telegram. Клієнт бачить їх на кожному кроці сценарію, зокрема на кроках з inline-меню. Наприклад: «Головне меню», «☎ +380…» (номер клієнта, щоб його бачив сапорт) і «Старт». Inline-кнопки під повідомленнями лишаються такими, як були.

Кнопки збираються у візуальному конструкторі. JSON писати не треба.

## Коли знадобиться

- Клієнт має з будь-якого місця сценарію повернутися в головне меню одним тапом.
- Сапорту потрібно бачити номер клієнта прямо в переписці.
- Потрібна кнопка «Старт», яка працює так само, як набраний `/start`.

## Перед початком

- [x] На інстансі увімкнено прапорець `ff_persistent_reply_keyboard`. Без нього картки в налаштуваннях нема. Попросіть увімкнути його сапорт або менеджера.
- [x] У сценарії є вузол з аліасом, куди має вести «Головне меню» (наприклад, `main_menu`).
- [x] Ви знаєте, в якій змінній сценарію зберігається телефон клієнта (наприклад, `phone`).
- [x] Ви можете відкривати й змінювати налаштування процесу. Окремих прав для цієї картки не треба.

## Покрокова інструкція

### 0. Підготуйте сценарій: аліас для «Головне меню»

Кнопка «Головне меню» веде у вузол «Connect To» з аліасом. Якщо такого вузла нема, кнопка мовчки не спрацює. Додайте його до початку роботи за розділом [Як додати аліас](#alias) і опублікуйте сценарій. Якщо кнопки «Головне меню» не буде, цей крок можна пропустити.

### 1. Відкрийте картку

1. Увійдіть у конструктор і в лівому меню натисніть **«Бібліотека процесів»**.
2. Відкрийте свій процес (бот з Telegram). Відкриється сторінка **«Налаштування <назва процесу>»**.
3. Прокрутіть сторінку до картки **«Постійна клавіатура Telegram»**.

Те саме можна зробити зі Scenario Builder: шестерня в тулбарі → **«Налаштування процесу»**.

Картки нема на сторінці? Не увімкнено прапорець `ff_persistent_reply_keyboard` (див. «Перед початком»). Telegram-канал має бути підключений до цього процесу.

<!-- screenshot: картка «Постійна клавіатура Telegram» з увімкненим перемикачем і попереднім переглядом -->

### 2. Увімкніть і наповніть кнопки

1. Увімкніть перемикач **«Увімкнено»**. Побачите блоки з кнопками й **«Як побачить клієнт»**.
2. Найпростіше: натисніть **«Заповнити прикладом»**. З'являться «Головне меню», `☎ {{phone}}` і «Старт». Далі підправте під себе.
3. Свою кнопку додайте так: **«Додати рядок»** → у рядку **«Кнопка»**. Рядків до 4, кнопок у рядку до 3.
4. У полі **«Текст кнопки»** впишіть підпис (до 64 символів). Щоб показати дані клієнта: **«Вставити змінну»** → впишіть назву змінної, наприклад `phone` → **«Вставити»**. У тексті з'явиться `{{phone}}`. Додайте поруч слово чи значок: `☎ {{phone}}`.
5. У полі **«Що робить кнопка»** оберіть дію (див. таблицю нижче).
6. Для дії «Перейти до кроку (аліас)» у полі **«Крок сценарію»** оберіть аліас, наприклад `main_menu`. Не бачите аліаса? Додайте його (крок 0) і натисніть **«Оновити список»**; кнопка **«Перейти до сценарію»** відкриє сценарій.
7. У полі **«Рядок перед меню»** впишіть короткий рядок, наприклад `Меню — під полем вводу 👇`. Порожнє поле означає, що бот надішле лише 👇.
8. Рядки можна міняти місцями: **«Підняти рядок вище»**, **«Опустити рядок нижче»**. Зайве прибирають **«Видалити кнопку»** і **«Видалити рядок»**.
9. Подивіться на **«Як побачить клієнт»**: це ті самі кнопки, як їх побачить клієнт. Кнопка зі змінною показана з прикладом значення.

Після кожного кроку зміни видно в блоці **«Як побачить клієнт»**. Якщо кнопки задано з помилкою, збереження покаже повідомлення (див. «Типові помилки при збереженні»).

### 3. Збережіть

1. Натисніть **«Зберегти»**. Побачите повідомлення про успіх.
2. Зачекайте до хвилини, поки бот підхопить зміну.

Вимкнути клавіатуру можна будь-коли: зніміть **«Увімкнено»** і збережіть. Вимкнення зберігається завжди, навіть якщо в кнопках є помилки.

### 4. Перевірте в Telegram

1. Відкрийте свого бота в Telegram і напишіть `/start`. Під полем вводу з'являться кнопки.
2. Натисніть «Головне меню»: бот веде до кроку з аліасом.
3. Введіть номер телефону за сценарієм: з'явиться кнопка «☎ +380…». Натисніть її: номер потрапляє в переписку, бот мовчить.
4. Натисніть «Старт»: бот починає сценарій спочатку.

Не вийшло? Дивіться «Типові помилки при збереженні» і «Що клієнт може сприйняти як баг» нижче.

### Три дії кнопки

| Що обрати в «Що робить кнопка» | Що відбувається після тапу |
|---|---|
| **Перейти до кроку (аліас)** | Бот переходить до вибраного кроку сценарію. |
| **Почати спочатку (/start)** | Те саме, що набраний `/start`: бот починає спочатку і забуває введені дані. |
| **Лише надіслати текст у чат** | Текст кнопки з'являється в переписці (його бачить сапорт). Бот нічого не відповідає і лишається на тому самому кроці. |

Кнопку, у якої змінна ще порожня, бот не показує. Наприклад, `☎ {{phone}}` з'явиться, щойно клієнт введе номер. Якщо жодної кнопки показати не вдається, бот працює як раніше, без клавіатури.

<a id="alias"></a>

## Як додати аліас для кнопки «Головне меню»

Кнопка «Головне меню» веде у вузол «Connect To» (Іменована точка входу) з потрібним аліасом. Якщо в сценарії такого вузла нема, кнопка мовчки не спрацює. У картці тоді з'являється підказка «У сценарії цього процесу ще немає аліасів».

1. Відкрийте сценарій цього процесу (у картці є кнопка **«Перейти до сценарію»**).
2. На початку головного меню додайте вузол **«Connect To»** і впишіть у поле **«Аліас»** назву, наприклад `main_menu`.
3. Опублікуйте сценарій.
4. Поверніться до картки, натисніть **«Оновити список»** і оберіть цей аліас у полі **«Крок сценарію»**.

<!-- screenshot: вузол «Connect To» з аліасом main_menu у Scenario Builder -->

## Як перевірити

1. Збережіть налаштування і зачекайте хвилину.
2. Напишіть боту `/start` у Telegram. Під полем вводу з'являться кнопки.
3. Натисніть кожну кнопку по черзі:
   - «Головне меню» — бот веде до вибраного кроку;
   - «☎ …» — номер з'являється в переписці, бот мовчить;
   - «Старт» — бот починає сценарій спочатку.

## Типові помилки при збереженні

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

| Повідомлення | Що робити |
|---|---|
| Не більше 4 рядків | Видаліть зайвий рядок. |
| Рядок N: не більше 3 кнопок | Перенесіть кнопку в інший рядок або видаліть. |
| Рядок N, кнопка M: вкажіть текст кнопки | Впишіть текст у «Текст кнопки». |
| Текст довший за 64 символи | Скоротіть текст. |
| Текст не може бути лише змінною — додайте слово поруч | Замість `{{phone}}` впишіть, наприклад, `☎ {{phone}}`. |
| Оберіть, що робить кнопка | Оберіть дію в «Що робить кнопка». |
| Оберіть крок сценарію | Для «Перейти до кроку (аліас)» оберіть крок зі списку. |
| Кроку з аліасом «…» немає в сценарії | Оберіть інший крок. Або додайте у сценарій вузол із цим аліасом і збережіть сценарій. |
| Така кнопка вже є — тексти мають відрізнятися | Змініть текст однієї з кнопок: однакових підписів не можна. |
| Рядок перед меню — не більше 200 символів | Скоротіть рядок. |
| Додайте хоча б одну кнопку | Додайте кнопку або вимкніть клавіатуру. |
| Постійна клавіатура вимкнена для цього інстансу | Попросіть сапорт увімкнути прапорець `ff_persistent_reply_keyboard`. |
| Недостатньо прав, щоб змінити клавіатуру | Попросіть доступ до цього процесу в адміністратора. |
| Невірний JSON | Виправте JSON у розділі «Розширено: JSON» або поверніться до візуальних кнопок. |

Якщо аліаса вже немає в сценарії, а кнопка збережена раніше, бот просто пропустить цю кнопку. Решта клавіатури працюватиме.

## Рядок перед меню

Inline-повідомлення (з кнопками під текстом) не може принести клавіатуру під полем вводу. Тому, коли клавіатури на екрані нема, а наступне повідомлення бота inline, бот спершу надсилає короткий рядок, а за ним inline-меню. Цей рядок з'являється лише тоді:

- на першому `/start` (і на набраному руками `/start`), коли стартовий крок — inline-меню;
- після розсилки;
- після закриття діалогу оператором з кнопкою закриття;
- після кроку з власною reply-клавіатурою;
- раз на добу, коли бот оновлює клавіатуру.

У історії діалогу в операторській панелі цього рядка нема.

## Що прибирає клавіатуру і коли вона повертається

Клавіатура не «прибита». З нею крок сценарію більше її не прибирає. Прибрати її можуть лише такі випадки.

| Що прибрало | Коли повертається |
|---|---|
| Текстова розсилка | З першою відповіддю бота за сценарієм, коли клієнт напише або натисне кнопку. |
| Розсилка з переходом на вузол (alias) | Одразу, з повідомленням цього вузла. |
| Кнопка закриття діалогу оператора | З першим повідомленням гілки закриття сценарію або з наступною відповіддю бота. |
| Крок з власними reply-кнопками (наприклад, «Оберіть місто») | З наступною відповіддю бота. Якщо текст кнопки кроку збігається з постійною кнопкою, спрацьовує кнопка кроку. |
| Клієнт згорнув клавіатуру | Бот її не розгортає, поки кнопки не змінились. Раз на добу бот може надіслати її знову, і тоді вона розгорнеться. |

## Оператор

- **Очікування оператора (OP-вузол з галочкою «продовжити сценарій»).** Поки оператор не написав, кнопки працюють як завжди.
- **Оператор написав.** Діалог належить оператору. Будь-який тап, і «Старт» теж, іде йому звичайним текстом, бот нічого не відповідає. OP-вузол без галочки підключає оператора одразу, тож тапи йдуть оператору з моменту OP-вузла.
- **Діалог закрито.** Бот продовжує сценарій, і клавіатура повертається з його першим повідомленням.

## Що клієнт може сприйняти як баг

- **«Бот інколи шле зайвий рядок "Меню — під полем вводу 👇"».** Це рядок перед меню: без нього Telegram не покаже клавіатуру перед inline-меню.
- **«Клавіатура зникла».** Її прибрала розсилка, кнопка закриття оператора або крок зі своїми кнопками. Вона повернеться з наступною відповіддю бота.
- **«Згорнув, а вона сама розгорнулась».** Раз на добу бот оновлює клавіатуру.
- **«Натиснув "Головне меню", а бот не відповів».** Діалог веде оператор: тап пішов йому текстом.
- **«Натиснув "Старт", і кнопка з номером зникла».** «Старт» — це повний `/start`: бот забуває номер, поки клієнт не введе його знову.
- **«Натиснув ☎, бот мовчить».** Так задумано: номер з'явився в переписці для сапорту.
- **«Кнопки з телефоном нема».** Бот ще не знає номера клієнта.
- **«У списку є пункт "Головне меню", а відкрилось головне меню».** У списку з reply-кнопками (search_list не inline) постійна кнопка перемагає пункт списку з тим самим текстом.
- **Під час опитування (наприклад, CSAT)** тап «Головне меню» піде в опитування як відповідь, а «Старт» почне сценарій спочатку.

## Обмеження

- Лише Telegram і лише приватні чати. У групах, Widget, Viber, WhatsApp, Instagram і e-chat клавіатури нема.
- Якщо сценарій сам викликає Telegram API (вузол «HTTP-запит» з URL Telegram або скрипт action jail з власним запитом) і такий виклик прибирає клавіатуру, бот цього не бачить. Клавіатура повернеться лише з наступною заміною або з оновленням раз на добу.
- Не більше 4 рядків, 3 кнопок у рядку, 64 символів у тексті кнопки, 200 символів у рядку перед меню.

## Розширено: JSON

Для досвідчених користувачів: розділ **«Розширено: JSON»** показує ті самі кнопки у вигляді JSON. Його можна редагувати напряму, а конструктор і перегляд оновляться. Поки JSON невірний, зміни не зберігаються.

```json
[
  [
    { "label": "Головне меню", "action": "goto_alias", "value": "main_menu" },
    { "label": "☎ {{phone}}", "action": "send_text" }
  ],
  [
    { "label": "Старт", "action": "command", "value": "/start" }
  ]
]
```

Дії в JSON: `goto_alias` (потрібен `value` з аліасом), `command` (лише `/start`), `send_text` (без `value`).

## Пов'язані матеріали

- [Стилізація кнопок клавіатури в Telegram](/uk/scenariodialog/explanation/telegram-keyboard-styling.md)
- [Про інлайн-клавіатуру в Telegram та Widget](/uk/scenariodialog/explanation/inline-keyboard.md)