Роботы: переменные и функции
Переменные — это память робота о клиенте: имя, город, выбранный тариф, телефон, сумма чека, счётчик напоминаний, метки источника. Их подставляют в тексты («%username%, спасибо, что были на вебинаре»), проверяют в условиях и меняют действиями. Файл нужен тому, кто пишет тексты с подстановками и строит логику на данных клиента.
Где найти: конструктор → окно любой ноды → панель «Подсказки» справа; действия «Переменная» и «Формула» — в ноде «Действие». Кто видит: право «Техблок/Роботы: смотреть свои / все»; менять — «Техблок/Роботы: редактировать свои / все».
Панель «Подсказки»
Рис. 1. Окно шага с панелью «Подсказки» справа
Справа в окне любой ноды — список всех переменных, доступных роботу, по группам: «Глобальные · Проект», «Пользователь · Робот», «Глобальные · Канал», «Система». Рядом с системными — пояснение. «Поиск переменной» фильтрует список, клик по переменной копирует её в буфер — вставьте в текст.
Стандартные переменные
Их робот заполняет сам из профиля клиента и данных перехода.
| Переменная | Что содержит |
|---|---|
%username% |
Имя клиента. Если имени в профиле нет — логин |
%fullname% |
Имя и фамилия |
%userid% |
Идентификатор клиента в VK или Telegram |
%city%, %country% |
Город и страна из профиля |
%sex% |
Пол: 1 — женский, 2 — мужской |
%relation% |
Семейное положение (VK) |
%phone% |
Телефон из профиля |
%group%, %unsubscribe% |
Ссылка на сообщество и на отписку (VK) |
%ref% |
Последняя реферальная метка |
%utm_source%, %utm_medium%, %utm_campaign%, %utm_content%, %utm_term% |
UTM-метки перехода |
%receipt_matched%, %receipt_amount%, %receipt_currency%, %receipt_status% |
Результат последней «Проверки чека» |
Также понимаются привычные написания {name}, {{first_name}} (это имя) и {{user_id}}.
Как подставить переменную в текст
- В тексте сообщения напишите переменную в одном из видов:
%city%,{{city}}или{city}. Регистр не важен. - Сохраните ноду и отправьте себе пробу самолётиком.
Готово: вместо переменной клиент увидит значение — «Ваш город — Казань».
Если значения нет, в тексте клиенту переменная просто исчезает, а лишние запятые и пробелы убираются: «Привет, {имя}!» превратится в «Привет!». В ссылках, теле вебхука и других служебных строках неизвестная переменная остаётся как есть.
Функции в тексте
| Конструкция | Пример | Результат |
|---|---|---|
[gender]…|…[/gender] |
Вы [gender]готов|готова[/gender] начать? |
Первый вариант — для мужчин, второй — для женщин. Пол неизвестен — первый |
[rand]мин:макс[/rand] |
Ваш счастливый номер — [rand]1:22[/rand] |
Случайное целое из диапазона включительно |
[rand]a|b|c[/rand] |
[rand]Отлично!|Прекрасно!|Супер![/rand] |
Случайный вариант из списка |
[date]формат[/date] |
Сегодня [date]dd.MM.yyyy[/date] |
Текущая дата в формате (dd — день, MM — месяц, yyyy — год, HH:mm — время) |
[city]есть|нет[/city] |
[city]Ждём вас из %city%|Ждём вас[/city] |
Первый вариант, если город заполнен, иначе второй |
[country]…|…[/country], [relation]…|…[/relation] |
— | То же для страны и семейного положения |
Типы и уровни переменных
У переменной два признака.
Тип — кому принадлежит значение:
- «Пользовательская» — у каждого клиента своё (его ответ, выбранный тариф);
- «Глобальная» — одно значение на всех (общий счётчик заявок, цена курса).
Уровень — где переменная видна:
| Комбинация | Где видна |
|---|---|
| «Пользовательская · Робот» | Только в этом роботе (по умолчанию) |
| «Пользовательская · Канал» | Во всех роботах этого аккаунта |
| «Глобальная · Робот» | Одно значение внутри робота |
| «Глобальная · Канал» | Одно значение во всём аккаунте |
| «Глобальная · Проект» | Одно значение во всём проекте (например, course_price) |
Переменные с одинаковым именем на разных уровнях — разные. Условие читает переменную с того уровня, который в нём выбран: «Переменная равна» уровня «Робот» не увидит одноимённую переменную уровня «Проект». В тексте при совпадении имён побеждает более «близкая»: переменная робота важнее переменной пользователя, та — глобальной, а глобальная — данных профиля.
Как создать переменную
- В действии «Установить переменную» (или в условии, экстракторе) выберите тип и уровень.
- Нажмите «Инициализировать переменную».
- Введите «Имя переменной...» (латиницей, например
tariff), выберите тип: «Строка», «Число», «Мапа» (JSON-объект{"ключ": "значение"}), «Массив строк» («Москва, Питер» или["Москва", "Питер"]), «Массив чисел» («1, 2, 3»). - При желании задайте начальное значение и нажмите «Создать».
Готово: переменная появится в списках выбора и в «Подсказках».
Калькулятор: как менять переменную
Значение меняют действия «Переменная» (подробно поля — в Действиях).
| Операция | Что делает | Если значение пустое или не число |
|---|---|---|
| «Установить» | Записывает значение | — |
| «Прибавить» / «Вычесть» | ± число | Считается 0 |
| «Умножить» | × число | Считается 1 |
| «Разделить» | ÷ число | Деление на 0 даёт 0 |
| «Добавить в конец» / «Добавить в начало» | Дописывает текст | Считается пустой строкой |
| «Случайное число» | Целое из диапазона «мин,макс» (через запятую), по умолчанию 1,100 | — |
| «Удалить переменную» | Убирает переменную | Ничего не происходит |
Что понимает «Установить»: true / false / null — логические значения; {...} и [...] — JSON-объект и список; 42, 3.14 — число; значение в скобках (...) — формула; всё остальное — текст как есть.
Формулы
Действие «Формула» вычисляет выражение и записывает результат в переменную. Выражения пишутся в скобках: сначала операция, потом аргументы. Все переменные доступны через vars: с уровнем — (:robot/имя vars), (:channel/имя vars), (:global/имя vars), стандартные — (:universal/username vars); без уровня — (get vars "имя").
Рис. 2. Редактор формулы, «Вставить переменную» и «Примеры формул»
Под полем — списки «Вставить переменную» по группам и «Примеры формул». Синтаксическую ошибку редактор подсвечивает: «Синтаксическая ошибка (позиция N) — проверьте скобки и кавычки».
Примеры:
| Задача | Формула |
|---|---|
| Прибавить 5 к переменной робота | (+ (:robot/x vars) 5) |
| Цена со скидкой 10 % | (Math/round (* (:global/course_price vars) 0.9)) |
| Условие | (if (> (:robot/age vars) 18) "adult" "minor") |
| Склеить имя и фамилию | (str (:channel/first_name vars) " " (:channel/last_name vars)) |
| Значение по умолчанию | (or (:global/discount vars) 0) |
| Размер платежа рассрочки | (Math/round (/ 24900 3)) → 8300 |
Формулы не превращают текст в число сами: если в переменной «12» строкой, используйте операции калькулятора («Прибавить», «Умножить») — они приводят значения к числу. Ошибка в формуле не останавливает робота, просто не даёт результата.
Практический сценарий: считаем напоминания и не надоедаем
Задача: напоминать о курсе не больше трёх раз.
- В ноде перед напоминанием добавьте «Прибавить» → «Пользовательская · Робот» → новая переменная
reminders(число, 0) → значение 1. - Поставьте «Условие» «Переменная больше»
reminders3. - «Если выполнено» → «Передать менеджеру», «Иначе» → «Напоминание».
- В тексте напоминания: «%username%, это уже [rand]второе|очередное[/rand] напоминание: места по цене вебинара сохраняем до пятницы».
Готово: после трёх напоминаний клиент уходит к менеджеру, а не получает четвёртое.
На телефоне
Панель «Подсказки» на узком экране скрыта; переменные можно вставить, набрав их вручную (%username%). Формулы удобнее писать на компьютере.
Частые вопросы
Переменная пустая в тексте. Проверьте имя и уровень: возможно, значение записано на уровне «Канал», а читаете «Робот». Посмотрите «Подсказки» — там видны переменные и уровни.
«Переменная больше» не срабатывает. В переменной текст, а не число («5 шт»). Запишите число отдельной переменной.
Случайное число не из диапазона. В «Случайное число» диапазон пишется через запятую: 1,6. В тексте [rand]1:6[/rand] — через двоеточие.
Можно ли использовать переменные в ссылке кнопки или в вебхуке? Да, %userid% и {{user_id}} подставляются и там.