# Довідник функцій

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

Функції з позначкою **проста** працюють скрізь, де є автопідстановки. Решта — лише в текстах повідомлень, умовах і деяких налаштуваннях блоків, див. [Де працюють автопідстановки](https://support.watbot.org/uk/chatbots/templates/where).

## Текст

| Функція | Що робить | Приклад | Результат |
|---|---|---|---|
| `upper(текст)` | Усі літери великі | `{{ upper("привіт") }}` | `ПРИВІТ` |
| `lower(текст)` | Усі літери малі | `{{ lower("ПРИВІТ") }}` | `привіт` |
| `capitalize(текст)` | Перша літера велика | `{{ capitalize("анна") }}` | `Анна` |
| `len(текст)` | Кількість символів | `{{ len("Привіт") }}` | `6` |
| `trim(текст)` | Прибирає пробіли по краях | `{{ trim("  так ") }}` | `так` |
| `replace(текст, що, на_що)` | Замінює всі входження | `{{ replace("050-000-00", "-", "") }}` | `05000000` |
| `substr(текст, початок, довжина)` | Частина тексту; початок з 0 | `{{ substr("Привіт", 0, 3) }}` | `При` |
| `number_format(число, знаків, дробовий_роздільник, роздільник_тисяч)` | Число з роздільниками. Типово 0 знаків, кома й пробіл | `{{ number_format(1234.5, 2) }}` | `1 234,50` |
| `urlencode(текст)` | Кодує текст для посилання | `https://site.ua/?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.org/uk/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+2 узимку й 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("UAH")`. З другим аргументом — число й ваш підпис: `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(" просто в цьому чаті") }}
```

Функції розділу — не прості. У виразі така функція має бути єдиною — її не можна ставити всередину умови чи іншої функції.