Сценарії
Змінні: глобальні, локальні та контактні
Типи змінних, ключі {name}, де створювати, як підставляються в повідомленнях, умовах і інтеграціях.
Три рівні змінних
У Epsenta змінні — це текстові поля профілю контакта, які підставляються в повідомлення, кнопки, умови, Google Таблиці, HTTP та розсилки. Синтаксис один: фігурні дужки навколо ключа.
Є три рівні налаштування плюс системні поля з мессенджера (ім'я, username, Telegram ID тощо).
- Глобальні (проєкт) — Налаштування → вкладка «Змінні»; однакові шаблони для всіх flows проєкту
- Локальні (flow) — панель «Локальні змінні» у редакторі конкретного сценарію; лише цей flow
- Контактні (персональні) — унікальні значення кожного підписника; змінюються блоками та тестами
- Системні — name, surname, fullname, username, id_telegram, phone — з профілю каналу
Синтаксис підстановки
У тексті пишіть {ключ} — латиниця, кирилиця, цифри та підкреслення всередині ключа (наприклад {quiz_score}, {ім_я}, {payment_url}).
Якщо значення порожнє, у повідомленні залишиться {ключ} як є — зручно помітити, що поле ще не заповнене.
У полі «Значення» блоку «Змінна» можна вказати інший плейсхолдер: {ім'я}, щоб записати вже обчислене значення.
- Повідомлення, підписи кнопок, опис оплати
- Умова / Switch — порівняння змінної з текстом або числом
- Розсилки — {first_name}, {username}, кастомні ключі
- Google Sheets — рядок шаблону: {email},{phone},{quiz_score}
- HTTP — URL і body з {змінними}
Глобальні змінні проєкту
Шлях: Налаштування → вкладка Змінні (не плутати з вкладкою «Google»). Тут задається каталог полів проєкту: ключ, назва для себе, тип, значення за замовчуванням.
Глобальні змінні — це шаблон, а не «поточний стан усіх користувачів». Для нового контакта дефолти можуть бути записані в профіль при першій взаємодії; далі значення живе в картці контакта.
Використовуйте глобальні для полів, які потрібні в багатьох flows: місто, джерело ліда, номер курсу, посилання на правила, стартовий бонус.
- Натисніть «+ Змінна», заповніть ключ і тип, «Зберегти»
- У редакторі блоків змінна з’явиться в списку «Глобальні (проєкт)»
- Змінити значення конкретній людині — Діалоги → контакт → змінні профілю
Змінні flow (проєкт)
Шлях: Flows → сценарій → вкладка Flow у правій панелі → блок «Змінні flow (проєкт)». Також можна створити з блоку («+ Створити нову змінну» у полі «Зберегти в змінну»).
Flow-змінна доступна у всіх сценаріях проєкту і її можна змінювати блоком Змінна або записом результату блоку.
Відмінність від глобальних (Налаштування → Змінні): глобальні у flow лише для читання — блок «Змінна» не дозволяє їх перезаписати.
У текстах використовуйте {ключ} так само, як глобальні. Значення для кожного контакта зберігається окремо.
Значення контакта (персональні)
У кожного підписника — свій набір значень у сховищі контакта (внутрішньо flow_state.variables). Саме вони підставляються в {ключ} під час діалогу.
Перегляд і ручне редагування: Діалоги → оберіть чат → бічна панель контакта → список змінних. Корисно виправити телефон або виставити бали вручну.
Автоматично заповнюють: «Запит вводу», «Запит телефону», блок Змінна, Тест/квіз, успішна Оплата, HTTP Request, Google Таблиці (поле «Результат у змінну»), цикл по масиву тощо.
Системні змінні
Не редагуються в Налаштуваннях — підставляються з даних каналу автоматично.
- {name} — ім'я (first_name)
- {surname} — прізвище
- {fullname} — ім'я + прізвище
- {username} — @username Telegram (якщо є)
- {id_telegram} — числовий ID
- {phone} — після блоку «Запит телефону» або збору контакту
- {level} / {рівень} — рівень мови контакта, якщо задано в профілі
Типи змінних
Тип задається при створенні глобальної або локальної змінної. Він підказує формат і фільтрує, які змінні можна обрати в певному блоці (наприклад, у Google Sheets для масиву — тип array/object/json).
- Текст — довільний рядок (ім'я, статус, коментар)
- Символ / код — короткий код, позначка рівня (A1, B2)
- Число (ціле) — бали, кількість, test_passed як 0/1
- Число (дробове) — суми з копійками
- Посилання — URL; у полі дефолту перевіряється формат посилання
- Масив (JSON) — список у JSON, для foreach та json_parse
- Словник (JSON) — об'єкт ключ→значення, dict_get / dict_set
- JSON — довільна JSON-структура для API та складних сценаріїв
Ключі та назви
Ключ (key) — те, що пишете в дужках: {quiz_score}. Краще латиниця + підкреслення, без пробілів: course_level, lead_source, payment_status.
Назва (label) — підпис для себе в адмінці («Бали квізу»); у боті не показується.
При створенні з назви «Нова змінна» ключ генерується автоматично (трансліт/очищення). Можна відредагувати ключ вручну — після зміни ключа оновіть усі {плейсхолдери} у flow.
Якщо назва латиницею без var_, у тексті можна використовувати короткий токен з назви (наприклад назва «Бали квізу» → {бали_квізу}); у списку вибору змінної показується підказка {токен}.
- Не дублюйте один ключ з різним сенсом у глобальних і локальних
- Для тестів використовуйте ключі з редактора тесту: quiz_score, test_passed, answer з answer_variable_key
- Результати інтеграцій: payment_url, sheets_result — поле «Змінна результату» в блоці
Пріоритет значень
Коли ключ збігається в кількох джерелах, застосовується такий порядок (останнє переважає): дефолт локальної змінної flow → персональне значення контакта → системне поле (name, phone…).
Тому персональні бали з квізу перекриють глобальний дефолт 0, а {name} з Telegram завжди доступне, якщо не перезаписали вручну в контакті.
Блоки, що записують змінні
- Змінна — записати фіксоване або {інша_змінна} в обраний ключ
- Запит вводу — відповідь користувача в variableKey
- Тест / квіз — бали, test_passed, відповіді по питаннях
- Оплата — payment_url, статус оплати (за налаштуванням блоку)
- HTTP Request — тіло відповіді в result variable
- Google Таблиці / Docs / Calendar — результат дії в змінну
- JSON parse, dict_set, array_build — структуровані дані для циклів
Блоки, що читають змінні
- Повідомлення, Медіа, Картки — текст і підписи
- Умова — поле «змінна» + оператор (дорівнює, більше, містить…)
- Switch — гілки за значенням однієї змінної
- Затримка / оплата / HTTP — параметри з підстановкою
- Розсилка — шаблон тексту для сегмента