Переменные-функции

Переменные-функции еще можно назвать текстовыми функциями потому что работают они прямо внутри текстовых полей. Функции отличаются наличием аргументов, которые выступают исходными данными. Текстовые функции подставляют результат своей работы в текст на место где находятся.

Общие особенности

Все функции обрамляются фигурными скобками: {}
В самом начале пишется название функции и двоеточие.
Например, для функции c названием var — {var:}
После двоеточия идут аргументы функции.
Разделитель между аргументами: | - вертикальная черта. Пример: {var:arg1|arg2}
Все функции поддерживают многоуровневую вложенность друг в друга!

Особенности функции VAR

Основная и самая популярная функция - {var:}. Она получает значение из переменной. Например {var:text} получает значение переменной text и подставляет его вместо себя в текст.

Кроме {var:} есть еще несколько функций, которые вы также можете использовать. Другие функции не просто подставляют значение переменной, а выполняют еще какую-то полезную операцию.

Набор переменных, по своей сути, это большой JSON объект. Внутри такого объекта могут быть разные типы данных: другие объекты, массивы, строки, числа и т. п.

Иногда нужно погрузиться внутрь одного из внутренних объектов. Для этого можно использовать символ точки: . Например:

{var:obj.deep.value} выведет 123 для JSON-переменной obj со значением {"deep":{"value": 123}}

А если нужно получить элемент массива, то используются квадратные скобки с индексом элемента, начиная с 0. Например получить тип первого вложения можно так:

{var:object.attachments[0].type}

Как видите, мы можем спокойно комбинировать разные опции написания, работая одновременно с многими типами данных.

Продвинутые возможности (автоматизаторам)

На самом деле простым погружением внутрь все не ограничивается. Функция var поддерживает еще очень много встроенных возможностей благодаря библиотеке JMESPath.

Официальная документация и песочница для тренировок находится на их сайте: https://jmespath.org/

Например, можно написать такую сложную структуру для получения идентификатора текущего контакта:

{user:contacts[?type=='{var:platform.contact.type}' && value=='{user:platform.id}' && bot_id==`{var:graph.integration.id}`] => [0].id}

Есть только пара особенностей. Чтобы не конфликтовать с обрамлением текстовых функций несколько символов заменены. В песочнице работают те которые слева, а в ботах - которые справа.

| → =>
{ → <
} → >

Значение по умолчанию

Первый аргумент функции var - название переменной. А второй - значение по умолчанию, если первое не найдено. Если ничего не написать во второй аргумент (не писать символ |), то значением по умолчанию будет undefined.

Несколько случайных примеров:

{var:name|default}
{var:number|0}
{var:object.attachments[?type=='photo'] => [0].code|Photo not found}

Если по умолчанию нужна пустая строка, то после символа | не нужно писать ничего (даже пробел). Пример: {var:name|}

Синонимы var - user, chat, author, contact, t

Есть ряд функций, которые по своей сути упрощают администратору жизнь. Их ключевая задача - сократить количество текста которое нужно написать чтобы достать нужную переменную. Покажем соответствия в таблице, где аргументом функции будет крайняя переменная

Профиль текущего чата (например, где было написано сообщение)

Функция	Переменная	Значение
{user:id}	{var:users.user.id}	Профиль текущего пользователя (например, кто написал сообщение)
{chat:title}	{var:users.chat.title}	Профиль текущего чата (например, где было написано сообщение)
{author:title}	{var:users.author.title}	Профиль текущего автора (например, кому отвечали - пользователь на сообщение которого получен ответ)
{contact:phone}	{var:users.user.contacts[?type=='phone'] => [0].value}	Значение первого контакта указанного типа
{t:field_name}	{var:template.field_name}	Значение поля field_name внутри текущего шаблона (только для случаев если схема запущена через шаблон)

Дополнительные фишки функций user - author

Показано на примере user, но для chat и author работает аналогично.

Переменная	Назначение
{user:full_name}	Имя + Фамилия для пользователя или Название для чата
{user:platform}	Эквивалент {var:platform.user}
{user:platform.url}	Надежная ссылка на профиль пользователя на внешней платформе (через ID)
{user:platform.link}	Красивая ссылка на профиль пользователя на внешней платформе (через public_name контакта). В некоторых случаях может быть не задана.
{user:hash}	Зашифрованный ID пользователя. Для использования в реферальных ссылках вместо явного ID. Пример синтаксиса: `?start=uh-{user:hash}`. Дает дополнительные преимущества - помещает профиль партнера в роль `{author:}` в момент срабатывания события Бот запущен

Случайное число - RAND

Cлучайное число в указанном диапазоне

{rand:|100|999}

Первое число - начиная с числа, второе - заканчивая. Числа учитываются включительно.

Примечание: рандом криптографический и не учитывает историю запросов, поэтому на малых диапазонах множественные повторы одинаковых результатов являются нормой

Случайный текст - ICIDENT

{incident:|one|two|three|four}

Список значений разделяется вертикальной чертой | . И начинается с такой же вертикальной черты.

Дополнительно функция поддерживает возможность передачи массива в первый аргумент. Например у вас есть переменная {var:array} у которой значение - JSON массив: ["one","two,"three"] . Работать будет аналогично. Пример:

{incident:{var:array}}

incident - случайный текст выбранный из всех предложенных вариантов
- Пример: {incident:|one|two|three|four}
- Пример результата: two

Оставить только цифры - NUM

Пример: {num:{var:product.price}|human}

num - оставить только цифры / числа / математику
- int - только цифры в виде одного числа - по умолчанию
- float - число с точкой
- math - числа (float) и математические операторы
- list - числа и запятые
- human - удобочитаемый формат
- price - удобочитаемый формат цены (сумма с копейками, если такие переданы)

Калькулятор - CALC

Посчитать простую математическую формулу (строковый аналог действия Калькулятор)

calc - посчитать простую математическую формулу (аналог действия Калькулятор)
- Параметры:
  - 1 - Переменная откуда брать формулу
  - 2 - Математическое выражение. Может содержать вложенные переменные. Если указаны и первый и второй параметры, то второй параметр в приоритете
  - 3 - Количество знаков после запятой
- Примеры:
  - а) {calc:1.234 + 2*3} = 7.234
    б) {calc:1.234 + 2*3|1} = 7.2
  - а) {var:expression} = 1.234 + 2*3
    б) {calc:{var:expression}}|1} = 7.2

Вывод аргумента по индексу - CASE

case - получение аргумента по его индексу, который находится в значении переменной

Пример: {case:{var:users.user.appeal}|обращение на вы|женский|мужской}
Суть функции:
- Варианты значений воспринимаются как массив с числовыми индексами.
- Нумерация элементов массива начинается с 0.
- Значение переменной переводится в число и воспринимается как индекс этого массива.
- И в итоге происходит поиск элемента по индексу,
  - или выводится значение переменной, если такой элемент с таким номером не найден.
- например, {var:users.user.appeal} может принимать такие значения:
  - 0 - пол не указан, 1 - женский, 2 - мужской.
  - Поэтому и пример выше сработает как положено.

Cклонение слов после числительных - LEXEME

lexeme - склонение существительных после числительных
- Пример: в корзине было {var:apples} {lexeme:{var:apples}|яблок|яблоко|яблока}
- Пример результата: в корзине было 24 яблока
- Суть: 0 или много → яблок, 1 → яблоко, 2 / 3 / 4 → яблока

Задать формат даты - DATE

Задает или меняет формат даты и времени. Позволяет получить текущее время.

Аргументы:

Переменная (сразу после двоеточия) с временем
- Если оставить пустой, то будет подставлено текущее время
- Должна быть в формате UNIX Timestamp: %s или %d-%m-%Y %H:%M:%S. Если эти форматы вам не подходят, то обязательно передайте свой третьим аргументом!
Формат исходящей даты. Пара примеров:
- %F %T - 2023-01-31 18:57:45
- %d-%m-%Y %H:%M - 31-01-2023 18:57
- %s - 1675180665 - количество секунд с 1 января 1970 года
Формат входящей даты (значения переменной или текущей)
- Форматы аналогичны входящим за исключением %s. Он не поддерживается, но его и не нужно задавать через формат. Достаточно просто подставить переменную со значением в формате UNIX Timestamp

Примеры:

{date:|%d-%m-%Y %H:%M}
{date:{var:object.text}|%F %T|%d-%m-%Y %H:%M}
{date:{var:date} {var:time}|%s|%d/%m/%Y %H:%M}
{date:|%s}
{date:|%s.%f} или {date:|%s-%f}

Таблица форматов даты

Директива	Описание	Пример результата
%a	%Weekday, short version%	Wed
%w	Weekday as a number 0-6, 0 is Sunday	3
%d	Day of month 01-31	31
%b	Month name, short version	Dec
%B	Month name, full version	December
%m	Month as a number 01-12	12
%y	Year, short version, without century	18
%Y	Year, full version	2018
%H	Hour 00-23	17
%I	Hour 00-12	05
%p	AM/PM	PM
%M	Minute 00-59	41
%S	Second 00-59	08
%f	Microsecond 000000-999999	548513
%s	UNIX Timestamp - количество секунд с 1 января 1970 года	1675180665
%z	UTC offset	+0100
%Z	Timezone	CST
%j	Day number of year 001-366	365

Директива	Описание	Пример результата
%U	%Week number of year, Sunday as the first day of week, 00-53%	52
%W	Week number of year, Monday as the first day of week, 00-53	52
%c	Local version of date and time	Mon Dec 31 17:41:00 2018
%C	Century	20
%x	Local version of date	12/31/18
%X	Local version of time	17:41:00
%%	A % character	%
%G	ISO 8601 year	2018
%u	ISO 8601 weekday (1-7)	1
%V	ISO 8601 weeknumber (01-53)	01