Перейти на сайт

Системные функции: полный справочник

Все системные функции BotMan в одном месте: назначение, параметры и короткие примеры использования в сценариях.

Системные функции помогают преобразовать данные прямо в сценарии: округлить число, изменить текст, получить часть строки, посчитать элементы массива или вывести сведения о подписке. В этой статье собраны все функции, доступные в каталоге BotMan, с параметрами и короткими примерами.

Как добавить системную функцию

  1. Откройте поле, в котором доступна подстановка переменных: например, текст сообщения, значение поля или математическую операцию.
  2. Нажмите </> «Переменные и функции».
  3. Откройте раздел «Системные функции» и выберите нужную функцию.
  4. Заполните параметры в появившемся окне и сохраните настройку.

BotMan сформирует запись автоматически. Примеры ниже показывают её технический вид — их удобно использовать, чтобы понять порядок параметров.

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

Числа

  • Генерация случайного числа — random. Возвращает целое число из указанного диапазона, включая обе границы. Параметры: минимум, максимум и необязательное резервное значение. Пример: {{random(1, 100)}}.
  • Округление числа — round. Округляет число до заданного количества знаков после запятой. Параметры: число, количество знаков (по умолчанию 0) и необязательное резервное значение. Пример: {{round({{user_field_1}}, 2)}}.
  • Форматирование десятичного числа — decimal_format. Преобразует число по шаблону. В шаблоне 0 означает обязательный разряд, # — необязательный, точка отделяет дробную часть, запятая — группы тысяч. Параметры: число, шаблон и необязательное резервное значение. Пример: {{decimal_format({{user_field_1}}, "#,##0.00")}}.

Дата и время

  • Форматирование даты и времени — format_date. Выводит дату в нужном виде. Параметры: дата, шаблон и необязательное резервное значение. Пример: {{format_date({{user_field_1}}, "dd.MM.yyyy HH:mm")}}. Частые обозначения: dd — день, MM — месяц, yyyy — год, HH:mm — время.
  • День недели сегодня (числом) — weekday. Не принимает параметров и возвращает число от 1 до 7: понедельник — 1, воскресенье — 7. Пример: {{weekday()}}.
  • День недели сегодня (строкой) — weekday_str. Не принимает параметров и возвращает название текущего дня недели. Пример: {{weekday_str()}}. Для условий обычно удобнее числовая функция weekday().

Дата и день недели вычисляются с учётом часового пояса проекта.

Текст

  • Удалить пробелы по краям — trim. Убирает пробелы в начале и конце строки. Пример: {{trim({{user_field_1}})}}.
  • Привести к нижнему регистру — lower. Пример: {{lower({{first_name}})}}.
  • Привести к верхнему регистру — upper. Пример: {{upper({{first_name}})}}.
  • Длина строки — length. Возвращает количество символов в тексте. Пример: {{length({{user_field_1}})}}.
  • Заменить часть текста — replace. Параметры: исходный текст, что заменить, на что заменить. Пустое третье значение удаляет найденный фрагмент. Пример: {{replace({{user_field_1}}, "-", "")}}.
  • Получить подстроку — substring. Параметры: текст, начальная позиция и необязательная длина. Отсчёт начинается с 0; отрицательная позиция считается с конца. Пример: {{substring({{user_field_1}}, 0, 5)}}.
  • Получить часть текста по разделителю — split_part. Параметры: текст, разделитель, номер части. Нумерация начинается с 1; отрицательное число выбирает часть с конца. Для переноса строки используйте \n. Примеры: {{split_part({{last_message}}, "\n", 2)}} и {{split_part({{user_field_1}}, "<SPLIT>", 1)}}.

Если нужной части для split_part нет, функция возвращает пустую строку. Она не удаляет пробелы автоматически: при необходимости используйте композицию {{trim({{split_part({{user_field_1}}, "<SPLIT>", 1)}})}}.

Массивы

Функции работают с пользовательскими и глобальными полями типа «Массив». В примерах user_field_x — служебное обозначение выбранного поля; выбирать массив рекомендуется через интерфейс.

  • Количество элементов — array_length. Возвращает размер массива; для пустого или отсутствующего массива — 0. Пример: {{array_length(user_field_x)}}.
  • Проверка наличия значения — array_contains. Для простого массива передайте массив и значение: {{array_contains(user_field_x, "Москва")}}. Для массива объектов передайте название свойства и значение: {{array_contains(user_field_x, "city", "Москва")}}. Результат — true или false.
  • Получение элемента — array_get. Параметры: массив, индекс и необязательное свойство объекта. Здесь индекс начинается с 0. Примеры: {{array_get(user_field_x, 0)}} и {{array_get(user_field_x, 0, "name")}}.
  • Сумма по массиву — array_sum. Складывает числовое свойство объектов. Пример: {{array_sum(user_field_x, "price")}}. Если третьим параметром указать количество, функция посчитает сумму произведений: {{array_sum(user_field_x, "price", "quantity")}}.

Подробнее о формате и изменении массивов: «Массивы: создание, формат и использование».

Агрегации по контактам

  • Количество контактов по значению поля — count_field. Принимает код пользовательского поля и считает контакты, соответствующие значению текущего пользователя. Пример: {{count_field(field_code)}}.
  • Топ контактов по полю — top_field. Принимает код поля и необязательный лимит. Возвращает нумерованный список значений с количеством контактов. По умолчанию выводится до 10 строк, максимальный лимит — 50. Пример: {{top_field(field_code, 10)}}.

Подписки и рекуррентные платежи

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

  • Дата окончания — subscription_end. Пример: {{subscription_end()}}.
  • Осталось дней — subscription_days_left. Пример: {{subscription_days_left()}}.
  • Статус — subscription_status. Например: «Активна», «Ожидает оплаты», «Льготный период» или «Отменена». Пример: {{subscription_status()}}.
  • Активна ли подписка — subscription_active. Возвращает «да» или «нет». Пример: {{subscription_active()}}.
  • Название тарифа — subscription_plan. Пример: {{subscription_plan()}}.
  • Стоимость — subscription_price. Возвращает сумму с валютой. Пример: {{subscription_price()}}.
  • Периодичность — subscription_period. Например: «Ежемесячно» или «Ежегодно». Пример: {{subscription_period()}}.

Пример с конкретным планом: {{subscription_status("planId")}}.

Данные из внешнего события

  • Данные из внешнего события — update. Получает значение из тела webhook по пути к полю. Параметры: путь и необязательное резервное значение. Пример: {{update(message.text, "Нет текста")}}.

Подробнее: «Данные из внешнего события».

Практический пример: разделить ответ ChatGPT на несколько сообщений

  1. В шаге «Действие» добавьте «Запрос к ChatGPT» и сохраните ответ в текстовое поле.
  2. В запросе попросите модель вернуть две или три части, разделённые уникальным маркером, например <SPLIT>.
  3. В следующем шаге «Сообщение» добавьте отдельный текстовый блок для каждой части.

Первое сообщение: {{trim({{split_part({{Ответ_ChatGPT}}, "<SPLIT>", 1)}})}}

Второе сообщение: {{trim({{split_part({{Ответ_ChatGPT}}, "<SPLIT>", 2)}})}}

Третье сообщение: {{trim({{split_part({{Ответ_ChatGPT}}, "<SPLIT>", 3)}})}}

Между текстовыми блоками можно добавить задержки, чтобы диалог выглядел естественнее.

Что важно проверить

  • Тип выбранного поля соответствует функции: число, дата, текст или массив.
  • Обязательные параметры заполнены и стоят в правильном порядке.
  • Индексы не перепутаны: substring и array_get начинают отсчёт с 0, а split_part — с 1.
  • Код пользовательского поля для агрегатных функций указан без опечаток.
  • Перед публикацией сценарий проверен через тестовый запуск.

Связанные статьи

👆 На этом пока всё