# Системные функции: полный справочник Source: https://docs.botman.pro/a/199-sistemnye-funktsii-polnyy-spravochnik Системные функции помогают преобразовать данные прямо в сценарии: округлить число, изменить текст, получить часть строки, посчитать элементы массива или вывести сведения о подписке. В этой статье собраны все функции, доступные в каталоге 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}}, "", 1)}}`. Если нужной части для `split_part` нет, функция возвращает пустую строку. Она не удаляет пробелы автоматически: при необходимости используйте композицию `{{trim({{split_part({{user_field_1}}, "", 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")}}`. Подробнее о формате и изменении массивов: [«Массивы: создание, формат и использование»](https://docs.botman.pro/a/192-massivy-sozdanie-format-i-ispolzovanie). ## Агрегации по контактам - **Количество контактов по значению поля —** **`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, "Нет текста")}}`. Подробнее: [«Данные из внешнего события»](https://docs.botman.pro/a/166-dannye-iz-vneshnego-sobytiya). ## Практический пример: разделить ответ ChatGPT на несколько сообщений 1. В шаге «Действие» добавьте [«Запрос к ChatGPT»](https://docs.botman.pro/a/40-zapros-k-chat-gpt) и сохраните ответ в текстовое поле. 2. В запросе попросите модель вернуть две или три части, разделённые уникальным маркером, например ``. 3. В следующем шаге «Сообщение» добавьте отдельный текстовый блок для каждой части. Первое сообщение: `{{trim({{split_part({{Ответ_ChatGPT}}, "", 1)}})}}` Второе сообщение: `{{trim({{split_part({{Ответ_ChatGPT}}, "", 2)}})}}` Третье сообщение: `{{trim({{split_part({{Ответ_ChatGPT}}, "", 3)}})}}` Между текстовыми блоками можно добавить задержки, чтобы диалог выглядел естественнее. ## Что важно проверить - Тип выбранного поля соответствует функции: число, дата, текст или массив. - Обязательные параметры заполнены и стоят в правильном порядке. - Индексы не перепутаны: `substring` и `array_get` начинают отсчёт с 0, а `split_part` — с 1. - Код пользовательского поля для агрегатных функций указан без опечаток. - Перед публикацией сценарий проверен через тестовый запуск. ## Связанные статьи - [Системные переменные](https://docs.botman.pro/a/75-sistemnye-peremennye) - [Массивы: создание, формат и использование](https://docs.botman.pro/a/192-massivy-sozdanie-format-i-ispolzovanie) - [Запрос к чат GPT](https://docs.botman.pro/a/40-zapros-k-chat-gpt) - [Шаг «Сообщение»: блок «Текст»](https://docs.botman.pro/a/224-shag-soobschenie-blok-tekst)