Екрани

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

1. Screen (Екран)

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

Використовуйте Screen, коли потрібно:

показати текстове повідомлення або кілька повідомлень;
додати зображення до повідомлення;
запропонувати користувачу кнопки для переходу в різні гілки сценарію;
прийняти довільний текст користувача через fallback-перехід.

Налаштування

Поле	Значення
`Name`	Назва екрана в редакторі
`Order`	Порядок екрана на рівні моделі
`IsOrderingEnabled`	Чи враховувати порядок елементів; за замовчуванням API використовує `false`
`IsKeyboardScreen`	Показувати reply keyboard замість inline-кнопок там, де це підтримує канал
`HideKeyboard`	Сховати клавіатуру; має пріоритет над `IsKeyboardScreen`
`HideInput`	Сховати поле введення там, де це підтримує канал
`Messages`	Список повідомлень із заголовком, текстом, URL зображення, порядком, затримкою та стилем
`IsQuickReply`	Чи надсилати кнопки повідомлення як quick replies там, де канал це підтримує; за замовчуванням API використовує `false`
`Buttons`	Кнопки екрана, які редагуються окремо від основної форми `Screen`
`ScreenButtonsCols`	Кількість колонок для кнопок, якщо значення більше нуля
`TargetKey`	Ключ для наступного вводу користувача; за замовчуванням `userInput`
`NextAction`	Fallback-перехід для довільного тексту, який не збігся з кнопкою

DelayAfterMs задає паузу перед відправленням цього повідомлення в мілісекундах. 0 (default) надсилає одразу. Затримка застосовується до кожного повідомлення, включно з першим або єдиним, і може імітувати набір тексту.

Кнопка має текст, порядок, дію, необов'язковий URL, режим Silent, ColumnSpan і візуальні налаштування. ColumnSpan задає ширину кнопки в колонках, від 1 до 3; null означає 1. Працює тільки коли ScreenButtonsCols більше за 1; на одноколонкових екранах ігнорується. Значення поза діапазоном 1-3 нормалізуються backend і додатково обмежуються кількістю колонок екрана.

Кнопка з дією створює окремий вихід до іншої ноди. URL-кнопка відкриває посилання замість переходу сценарієм.

Connections

Вхід: один стандартний connector.
Виходи: окремий вихід для кожної кнопки з дією.
Додатковий вихід: NextAction як fallback для довільного вводу.

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

Після відповіді користувача backend спочатку шукає кнопку на останньому екрані, потім глобальний збіг кнопки, pending UserInput, і лише після цього використовує Screen.NextAction.

Змінні і шаблони

У Message.Title, Message.Text і Message.PhotoUrl працюють змінні #var та JS-вирази {{ JS }}. Текст і URL звичайних кнопок не проходять через runtime renderer.

Під час показу екрана backend декларує порожню змінну:

#node.{screenId}.{TargetKey}

Після наступного повідомлення користувача в цю змінну записується реальне значення. Якщо TargetKey дорівнює city, після вводу користувача можна використовувати:

#node.{screenId}.city
#city
#userInput

Приклад

Event -> Screen "Оберіть тариф"
              | Button "Basic" -> Set memory
              | Button "Pro"   -> Set memory
              | NextAction      -> Input

Важливі особливості

Порожні повідомлення без видимого тексту, заголовка або зображення не показуються.
Якщо JS у повідомленні завершується помилкою, Screen не буде показано, а виконання сценарію перейде в failed-стан.
Screen не використовується в синхронному AI tool, бо tool не може чекати нового повідомлення людини.
Viber, Viber Business, Widget і Telegram можуть по-різному відображати клавіатуру, стилі й додаткові прапорці.

2. Keyboard Screen (Екран з клавіатурою)

Keyboard Screen працює за тими самими правилами, що й Screen: показує повідомлення, може мати кнопки, ставить сценарій на паузу й обробляє наступну дію користувача через кнопки або NextAction.

Основна відмінність: кнопки показуються як reply keyboard там, де це підтримує канал. У панелі ця нода винесена окремо, щоб швидко створювати екрани з клавіатурою без ручного перемикання режиму IsKeyboardScreen.

Поле	Значення
`IsKeyboardScreen`	Вмикає режим reply keyboard
`HideKeyboard`	Якщо увімкнено, ховає клавіатуру і має пріоритет над `IsKeyboardScreen`
`ScreenButtonsCols`	Керує кількістю колонок для кнопок, якщо значення більше нуля

Усі інші правила для messages, buttons, connections, TargetKey, NextAction, змінних #node.{screenId}.{TargetKey} і шаблонів #var / {{ JS }} такі самі, як у Screen.

Приклад:

Event -> Keyboard Screen "Головне меню"
              | Button "Каталог"  -> Screen
              | Button "Підтримка" -> Agent trigger

Фактичний вигляд клавіатури залежить від каналу: Viber, Viber Business, Widget і Telegram можуть відображати її по-різному.

Share phone screen (SharePhoneScreen) — спеціалізований екран із native-кнопкою “поділитися контактом”. Він потрібний, коли бот має отримати не просто введений номер, а підтверджений contact-share event від Telegram або Viber Bot.

Налаштування

Нода успадковує основні налаштування Screen: повідомлення, Name, порядок, TargetKey, HideInput і NextAction. Окремо налаштовується одна share-кнопка:

Поле	Значення
`Text`	Основний текст кнопки
`SubText`	Додатковий текст кнопки, якщо канал його підтримує
`Silent`	Чи виконувати дію без видимого повідомлення
Visual options	Візуальні параметри кнопки, доступні для каналу

Додаткові звичайні кнопки не підтримуються: backend залишає рівно одну share-кнопку.

Connections

Вхід: один стандартний connector.
Вихід: один NextAction, який використовується як fallback для наступного вводу.

Сама SharePhoneScreen не перевіряє, що номер прийшов саме з native contact-share. Для цього після неї варто ставити Input із InputType=Phone і RequireContactShare=true.

Рекомендована схема:

Share phone screen
  -> Input(InputType=Phone, RequireContactShare=true)
  -> наступна нода

Змінні і шаблони

Повідомлення, photo URL і текст share-кнопки підтримують #var та {{ JS }}.

Після contact callback доступні:

#node.{shareScreenId}.{TargetKey}
#userInput

Якщо TargetKey відрізняється від userInput, backend також додає #{TargetKey}. Downstream Input створює власну нормалізовану змінну, тому для подальшої логіки краще використовувати саме результат Input.

Важливі особливості

Telegram і Viber Bot передають Source=ContactShare.
Для Viber Business аналогічне джерело у перевіреному callback не встановлюється.
Нода не використовується в синхронному AI tool, бо очікує нову дію користувача.

4. Input (Поле вводу)

Input (UserInput) приймає останній ввід користувача, перевіряє тип, нормалізує значення й направляє execution у success-, prompt- або invalid-гілку.

Налаштування

Поле	Значення
`InputType`	`Text`, `Integer`, `Decimal`, `Date`, `Boolean` або `Phone`
`TrimInput`	Прибирати пробіли на початку й у кінці; за замовчуванням `true`
`RequireContactShare`	Для `Phone` приймати лише native contact-share event
`TargetKey`	Ім'я вихідної змінної; за замовчуванням `userInput`
`NextAction`	Гілка валідного вводу
`PromptScreenAction`	Screen-підказка, якщо вводу ще немає
`InvalidInputScreenAction`	Screen помилки, якщо значення не пройшло перевірку

InputKey у бібліотеці існує, але current API завжди використовує userInput і не дає змінити це поле.

Connections

Вхід: один стандартний connector.
Next: може вести до будь-якої звичайної ноди.
Prompt і Invalid: мають вести саме до Screen або Share phone screen.

Коли input відсутній або порожній, нода використовує PromptScreenAction, а за його відсутності — InvalidInputScreenAction. Для непорожнього, але невалідного input порядок зворотний: InvalidInputScreenAction, потім fallback на PromptScreenAction.

Якщо жодна action не веде до Screen або Share phone screen, execution завершується помилкою стану.

Нормалізація

Тип	Правило і результат
`Text`	Будь-який непорожній рядок
`Integer`	`long`, записаний в invariant-форматі
`Decimal`	Invariant або server current culture, результат invariant
`Date`	Розпізнана дата, результат ISO 8601 (`O`)
`Boolean`	`true` / `false`, `1` / `0`, `yes` / `no`, `y` / `n`, `так` / `ні`; результат `True` або `False`
`Phone`	Лише `+` і цифри після очищення, від 7 до 15 цифр

Валідний результат зберігається як:

#node.{id}.{TargetKey}

Приклад

Input(age)
  ├─ Prompt  -> Screen "Введіть вік"
  ├─ Invalid -> Screen "Потрібне ціле число"
  └─ Next    -> Condition "#node.12.age >= 18"

Важливі особливості

Нода читає лише input із точним ключем userInput, а не випадковий output попередньої ноди.
RequireContactShare має ефект лише разом з InputType=Phone.
Валідний input без NextAction дає invalid chain state.
Нода не використовується в синхронному AI tool, бо може перейти в стан очікування.

5. Carousel screen (Карусель)

Carousel screen (CarouselScreen) показує карусель карток: кожна картка має заголовок, необов'язковий підзаголовок, зображення, default action URL і кнопки картки. Підтримується тільки для Instagram.

Як і Screen, це нода-пауза: після показу каруселі сценарій чекає наступну дію користувача. Користувач може натиснути кнопку картки або надіслати довільний ввід, який піде через fallback-перехід.

Налаштування

Поле	Значення
`Name`	Назва екрана в редакторі
`Order`	Порядок екрана на рівні моделі
`IsOrderingEnabled`	Чи враховувати порядок елементів
`TargetKey`	Ключ для наступного вводу користувача; за замовчуванням `userInput`
`NextAction`	Fallback-перехід для довільного вводу
`Cards[]`	Картки каруселі: `Title`, `Subtitle`, `ImageUrl`, `DefaultActionUrl` і `Buttons[]`

Кожна картка повинна мати Title до 80 символів. На картці може бути до 3 кнопок. Кожна кнопка картки повинна мати Text і рівно одне з:

Action, щоб перевести сценарій в іншу гілку;
Url, щоб відкрити посилання.

Connections

Вхід: один стандартний connector.
Виходи: окремий вихід для кожної кнопки картки з Action.
Додатковий вихід: NextAction як fallback для довільного вводу.

Звичайні не-карусельні кнопки екрана для Carousel screen не підтримуються; використовуйте кнопки карток.

Змінні і шаблони

Після вибору користувача або fallback-вводу значення доступне як:

#node.{screenId}.{TargetKey}

Важливі особливості

Карусель повинна містити від 1 до 10 карток.
Кожна кнопка картки з Action створює окремий вихід ноди.
Carousel screen не використовується в синхронному AI tool, бо очікує дію користувача.

Екрани

1. Screen (Екран)

Налаштування

Connections

Змінні і шаблони

Приклад

Важливі особливості

2. Keyboard Screen (Екран з клавіатурою)

3. Share phone screen (Екран: поділитись номером)

Налаштування

Connections

Змінні і шаблони

Важливі особливості

4. Input (Поле вводу)

Налаштування

Connections

Нормалізація

Приклад

Важливі особливості

5. Carousel screen (Карусель)

Налаштування

Connections

Змінні і шаблони

Важливі особливості