# Справочник функций

Функция вызывается так: `{{ имя(аргумент1, аргумент2) }}`. Аргументы — текст в кавычках, числа, переменные (`$имя`) и, в [выражениях](https://support.watbot.ru/chatbots/templates/expressions), результаты других функций.

Функции, отмеченные **простая**, работают везде, где есть автоподстановки. Остальные — только в текстах сообщений, условиях и некоторых настройках блоков, см. [Где работают автоподстановки](https://support.watbot.ru/chatbots/templates/where).

## Текст

| Функция | Что делает | Пример | Результат |
|---|---|---|---|
| `upper(текст)` | Все буквы большие | `{{ upper("привет") }}` | `ПРИВЕТ` |
| `lower(текст)` | Все буквы маленькие | `{{ lower("ПРИВЕТ") }}` | `привет` |
| `capitalize(текст)` | Первая буква большая | `{{ capitalize("анна") }}` | `Анна` |
| `len(текст)` | Количество символов | `{{ len("Привет") }}` | `6` |
| `trim(текст)` | Убирает пробелы по краям | `{{ trim("  да ") }}` | `да` |
| `replace(текст, что, на_что)` | Заменяет все вхождения | `{{ replace("8-999-000", "-", "") }}` | `8999000` |
| `substr(текст, начало, длина)` | Часть текста; начало с 0 | `{{ substr("Привет", 0, 3) }}` | `При` |
| `number_format(число, знаков, дробный_разделитель, разделитель_тысяч)` | Число с разделителями. По умолчанию 0 знаков, запятая и пробел | `{{ number_format(1234.5, 2) }}` | `1 234,50` |
| `urlencode(текст)` | Кодирует текст для ссылки | `https://site.ru/?q={{ urlencode($запрос) }}` | |
| `randomText(вариант1, вариант2, ...)` | Один вариант наугад | `{{ randomText("Привет", "Здравствуйте") }}` | |
| `strRandom(длина, большие)` | Случайная строка из букв и цифр, до 1000 символов. `true` вторым аргументом — только большие буквы | `{{ strRandom(8, true) }}` | `K3JD8QWZ` |

Все функции раздела — **простые**.

## Математика

| Функция | Что делает | Пример | Результат |
|---|---|---|---|
| `round(число, знаков)` | Округление, по умолчанию до целого | `{{ round(2.567, 2) }}` | `2.57` |
| `ceil(число)` | Округление вверх | `{{ ceil(2.1) }}` | `3` |
| `floor(число)` | Округление вниз | `{{ floor(2.9) }}` | `2` |
| `abs(число)` | Модуль числа | `{{ abs(-5) }}` | `5` |
| `sqrt(число)` | Квадратный корень | `{{ sqrt(16) }}` | `4` |
| `max(a, b, ...)` | Наибольшее | `{{ max(3, 7, 5) }}` | `7` |
| `min(a, b, ...)` | Наименьшее | `{{ min(3, 7, 5) }}` | `3` |
| `rand(от, до)` | Случайное целое число | `{{ rand(1, 100) }}` | |

Все функции раздела — **простые**. Сложение, вычитание, умножение, деление и степень пишутся знаками, см. [Арифметика](https://support.watbot.ru/chatbots/templates/expressions#арифметика).

### Устаревшие функции

Эти функции продолжают работать, но в новых текстах пишите знаки — так короче и понятнее:

| Устаревшая функция | Как писать теперь |
|---|---|
| `sum($a, $b)`, `сумма($a, $b)` | `{{ $a + $b }}` |
| `diff($a, $b)`, `разность($a, $b)` | `{{ $a - $b }}` |
| `multiplication($a, $b)`, `произведение($a, $b)` | `{{ $a * $b }}` |
| `div($a, $b)`, `деление($a, $b)` | `{{ $a / $b }}` |
| `pow($a, $b)` | `{{ $a ** $b }}` |

Например, вместо `{{ sum($цена, $доставка) }}` — `{{ $цена + $доставка }}`.

## Дата и время

> [!WARNING]
> Время считается по UTC. Московское время — UTC+3: `{{ date("H:i", "+3 hours") }}`.

| Функция | Что делает |
|---|---|
| `date(формат, дата)` | Дата в нужном формате. Без даты — сейчас. Дата — `"2026-10-02"`, `"+7 days"`, `"next monday"` и т. п. |
| `time()` | Текущее время в секундах с 1970 года (Unix time) |
| `modifyDateTime(дата, формат_даты, формат_вывода, сдвиг)` | Разбирает дату из переменной по её формату, сдвигает и выводит в другом формате |
| `modifyUnixTime(unix_time, сдвиг, формат)` | Сдвигает Unix time; с форматом выводит дату, без формата — новое Unix time |

Примеры:

```
Сегодня {{ date("d.m.Y") }}
Ждём вас {{ date("d.m.Y", "+3 days") }}
Запись перенесена на {{ modifyDateTime($дата_записи, "d.m.Y", "d.m.Y", "+1 day") }}
Доступ до {{ modifyUnixTime(time(), "+30 days", "d.m.Y") }}
```

Основные символы формата:

| Символ | Значение | Пример |
|---|---|---|
| `d` | день с нулём | `02` |
| `j` | день без нуля | `2` |
| `m` | месяц с нулём | `10` |
| `n` | месяц без нуля | `10` |
| `Y` | год | `2026` |
| `H` | часы, 24-часовой формат | `14` |
| `i` | минуты | `05` |
| `s` | секунды | `09` |
| `N` | день недели, 1 — понедельник | `5` |

Сдвиг пишется по-английски: `"+1 day"`, `"-2 hours"`, `"+1 month"`, `"next friday"`.

Все функции раздела — **простые**.

> [!NOTE]
> В старых сценариях встречается подстановка через знак вопроса: `{{ date("d.m.Y", "+? days", $дни) }}` — `?` заменяется следующим аргументом. Это продолжает работать, но в выражениях проще склеить: `{{ date("d.m.Y", "+" ~ $дни ~ " days") }}`.

## Условия

| Функция | Что делает |
|---|---|
| `printByCondition(a, оператор, b, если_да, если_нет)` | Сравнивает `a` и `b` и выводит один из вариантов. Операторы: `=`, `!=`, `>`, `>=`, `<`, `<=`. Если `a` или `b` пустые — выводит `если_нет` |
| `printByExistsCondition(значение, если_да, если_нет)` | `если_да`, если значение не пустое, иначе `если_нет` |

```
{{ printByCondition($баллы, ">=", 100, "Подарок ваш!", "Копите дальше") }}
{{ printByExistsCondition($телефон, "Телефон сохранён", "Оставьте телефон") }}
```

Обе функции — **простые**. В выражениях удобнее условный оператор: `{{ $баллы >= 100 ? "Подарок ваш!" : "Копите дальше" }}`.

## Данные контакта и бота

| Функция | Что делает | Простая |
|---|---|---|
| `var("имя")` | Значение переменной контакта; удобно для имён с пробелами | да |
| `global("имя")` | Значение глобальной переменной | да |
| `printContactTags()` | Теги контакта через запятую | да |
| `printContactVariables()` | Все текстовые переменные контакта списком «- имя: значение» | да |
| `printGlobalVariables()` | Все глобальные переменные бота списком «- имя: значение» | да |
| `getBalance("валюта", "подпись")` | Баланс счёта контакта в валюте, с её знаком: `getBalance("RUB")`. Со вторым аргументом — число и ваша подпись: `getBalance("PTS", "баллов")` → `150 баллов` | нет |
| `getCartAmount()` | Сумма корзины старого блока «Корзина» | нет |

> [!WARNING]
> `printGlobalVariables()` выводит **все** глобальные переменные. Не используйте её в сообщениях контактам, если в глобальных переменных хранятся ключи или пароли.

## Переменные

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

| Функция | Что делает |
|---|---|
| `setSumVariablesIntoVariable("итог", a, b, ...)` | Сохраняет сумму в переменную `итог` |
| `setMultiplicationVariablesIntoVariable("итог", a, b, ...)` | Сохраняет произведение в переменную `итог` |

Слагаемые — числа или имена переменных в кавычках, нужно хотя бы два: `{{ setSumVariablesIntoVariable("итог", "цена", "доставка", 100) }}`.

Для расчётов удобнее блок «Операция над переменной» — там же можно использовать выражения.

## Списки

| Функция | Что делает |
|---|---|
| `getListRow("id записи", "шаблон")` | Выводит одну запись списка по шаблону |
| `getListRows("id списка", "шаблон", сколько, "поле сортировки", "asc" или "desc", "разделитель")` | Выводит записи списка по шаблону, по умолчанию 10, не больше 50, каждая с новой строки |

В шаблоне поле записи пишется в одинарных фигурных скобках: `{Название}`, `{Цена}`. В `getListRows` в шаблон можно вставить переменную контакта: `{$город}`.

```
{{ getListRows("6523f0c2a1b2c3d4e5f60718", "{Название} — {Цена} ₽", 5, "Цена", "asc") }}
```

Бот читает только списки своего владельца.

## Реферальная программа

| Функция | Что выводит |
|---|---|
| `getInviteLink()` | Личную реферальную ссылку контакта (Telegram, MAX) |
| `getDirectInviteLink(id_сценария)` | Прямую ссылку на бота с реферальным параметром; со сценарием — запуск этого сценария |
| `getInviteLinkWithSchema(id_сценария)` | Реферальную ссылку на запуск сценария |
| `getLinkBySchema(id_сценария)` | Ссылку на запуск сценария, без реферального параметра |
| `getReferrals(сколько, "тег")` | Список приглашённых контактом (первая линия): «1. Имя - username», по умолчанию 10, не больше 100. С тегом — только с этим тегом |
| `getReferralsByDepth(линия, сколько, "тег")` | То же для указанной линии |
| `getReferralsCount("тег")` | Количество приглашённых на всех линиях |
| `getReferralsCountByDepth(линия, "тег")` | Количество приглашённых на указанной линии; 0 — на всех |
| `getReferrer(линия)` | Того, кто пригласил контакта; 2 — того, кто пригласил пригласившего, и т. д. |
| `getReferrers(сколько_линий, с_линии, "тег")` | Список пригласивших вверх по цепочке |

Функции раздела — не простые. Устаревшие варианты с `Telegram` в имени (`getTelegramInviteLink` и другие) работают так же.

## Разные тексты для мессенджеров

Текст внутри функции увидят только контакты из указанного мессенджера, остальным подставится пустое место:

| Функция | Мессенджер |
|---|---|
| `messageToTelegram("текст")` | Telegram |
| `messageToViber("текст")` | Viber |
| `messageToVK("текст")` | ВКонтакте |
| `messageToWeb("текст")` | Веб-чат на сайте |

```
Напишите нам{{ messageToTelegram(" в Telegram: @example_support") }}{{ messageToWeb(" прямо в этом чате") }}
```

Функции раздела — не простые. В выражении такая функция должна быть единственной — её нельзя ставить внутрь условия или другой функции.