# Данные приложения

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

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

Переменные не нужно заводить заранее. Достаточно указать имя там, куда записывается значение, — в поле «Переменная» у элемента или блока. Конструктор запоминает имена из схемы и подсказывает их при вводе.

![Подсказка имён переменных в поле «Переменная»](https://support.watbot.ru/_media/ru/02-mini-apps/_images/variable-hint.webp?v=1791781230)

Откуда берутся значения:

| Источник | Что записывает |
|---|---|
| Поля ввода | То, что человек ввёл или выбрал, — в переменную из поля «Переменная» |
| «Записи списка» и другие элементы, где выбирают строку | Идентификатор выбранной строки — в переменную из настроек элемента |
| «HTTP-запрос» | Ответ целиком, код ответа и отдельные значения из ответа |
| «Найти запись» | Колонки найденной записи |
| «Добавить запись», «Форма записи» | Идентификатор новой записи |
| «JavaScript», код приложения, «HTML-код» | Переменные, которые разрешено писать коду, — см. [Код в приложении](https://support.watbot.ru/mini-apps/code) |

Ещё несколько переменных приложение заполняет само при запуске. Записать в них что-то своё нельзя:

| Переменная | Что в ней |
|---|---|
| `launchSource` | Откуда открыто приложение: `telegram`, `max`, `webchat`, `pwa` или `browser` |
| `startParam` | Параметр ссылки запуска — то, что стоит после `startapp`. Как его передать — на странице [Версии и публикация](https://support.watbot.ru/mini-apps/publish) |
| `contactTags` | Теги контакта бота через запятую |
| `appTags` | Теги пользователя приложения через запятую |

Переменные человека видно в его карточке в разделе «Пользователи», там же их можно поправить. Ход переменных в предпросмотре показывает панель «Отладка».

**Ограничения.** Имя переменной — до 64 символов, значение — до 4096. У одного пользователя — до 500 переменных: новые сверх этого не записываются.

## Подстановки

Значение переменной подставляется в текст двойными фигурными скобками: `{{ имя }}`. Подстановки работают в текстах и заголовках экранов, в подписях, в значениях полей по умолчанию, в адресе и теле HTTP-запроса, в значениях колонок и условиях отбора записей, в сообщениях бота.

Пример: поле ввода пишет имя в переменную `name`, а на следующем экране заголовок «Спасибо, `{{ name }}`!» превратится в «Спасибо, Анна!».

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

> [!TIP]
> В полях конструктора, куда пишется значение, начните вводить имя — подсказка вставит подстановку целиком. В полях, куда записывается результат, подсказка вставляет голое имя переменной.

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

Если приложение открыто из бота и человек этому боту писал, доступны поля его контакта:

| Подстановка | Что в ней |
|---|---|
| `{{ contact.id }}` | Номер контакта |
| `{{ contact.name }}`, `{{ contact.first_name }}`, `{{ contact.last_name }}` | Имя целиком, имя, фамилия |
| `{{ contact.username }}` | Ник в мессенджере |
| `{{ contact.phone }}`, `{{ contact.email }}`, `{{ contact.address }}` | Телефон, почта, адрес |
| `{{ contact.source }}` | Канал контакта |
| `{{ contact.created_at }}` | Когда контакт появился в боте |
| `{{ contact.start_message }}` | Первое сообщение боту |
| `{{ contact.telegram_id }}`, `{{ contact.max_id }}` | Идентификатор в Telegram и MAX |

Свои переменные контакта тоже читаются с приставкой: `{{ contact.city }}` — переменная `city` из карточки контакта.

Переменные приложения и переменные контакта бота — разные. Значение из поля приложения в контакт не попадает, а переменная контакта не видна в приложении без приставки `contact.`. Записать переменную в контакт может только код блока «JavaScript». У гостя из браузера контакта нет — поля `contact.` пусты.

## Списки

Приложение хранит данные в списках проекта — тех же, с которыми работают чат-боты: [Списки](https://support.watbot.ru/lists). Список, заполненный в приложении, виден в разделе «Списки» меню проекта, и наоборот. Чужой список — из другого проекта — приложение не откроет.

Приложение может заполнять поля типов «Текст», «Число», «Денежный», «Логический», «Дата» и «Дата и время». Поля «Файл», «Картинка», «ID контакта» и «ID бота» заполнить из приложения нельзя.

| Задача | Чем делать |
|---|---|
| Показать каталог, расписание, отзывы | Элемент «Записи списка» |
| Открыть одну запись на отдельном экране | Нажатие на запись кладёт её идентификатор в переменную (по умолчанию `recordId`), следующий экран показывает её элементом «Карточка записи» или раскладывает по переменным блоком «Найти запись» |
| Принять заявку или анкету | Элемент «Форма записи» или поля ввода плюс блок «Добавить запись» |
| Дать человеку поправить свою запись | «Форма записи» в режиме «Меняет запись» или блок «Изменить запись» |
| Удалить запись | Блок «Удалить запись» |

### Отбор и сортировка

У «Записей списка» и блоков записей есть «Условия»: «Колонка», «Условие» и «Значение». Условия: «Равно», «Содержит», «Начинается с», «Заканчивается на», «Больше», «Меньше», «Пусто», «Заполнено». Условий — до 20.

В значение можно подставить переменную — тогда отбор зависит от того, что выбрал человек. Например, поле поиска пишет в `query`, а условие «Название» «Содержит» `{{ query }}` показывает подходящие записи.

«Сортировка» — колонка и направление «По убыванию» или «По возрастанию». Пусто — сначала новые записи.

«Сколько показывать» — столько записей загружается за один раз; с отметкой «Подгружать при прокрутке» следующие подгружаются, когда человек долистал до конца. За один раз приложение отдаёт не больше 50 записей.

![Элемент «Записи списка»: что показывать, отбор и сортировка](https://support.watbot.ru/_media/ru/02-mini-apps/_images/records-element.webp?v=1791781230)

### Свои записи

Запись можно закрепить за человеком, который её создал: отметка «Запись принадлежит пользователю» у «Формы записи» или «Привязать запись к текущему пользователю» у блока «Добавить запись». Это работает и у гостя из браузера.

С отметкой «Только записи текущего пользователя» элемент или блок видит только записи этого человека — так делают «мои заявки», «мои заказы», избранное. У блоков «Изменить запись» и «Удалить запись» эта отметка включена по умолчанию: без неё человек мог бы подставить чужой идентификатор и изменить чужую запись.

## Формы

Элемент «Форма записи» — короткий путь от экрана к записи: каждое поле формы — колонка списка, а отправка сразу создаёт или меняет запись. Отдельный блок не нужен; выход формы срабатывает после успешной отправки.

1. Добавьте на экран «Форма записи» и выберите «Список».
2. В «Что делает форма» оставьте «Добавляет запись» или выберите «Меняет запись». Для изменения укажите «Какую запись менять» — обычно переменную, которую кладёт нажатие на запись списка. Отметка «Показать в полях значения записи» заполнит поля текущими значениями.
3. Добавьте «Поля формы» — по одному или кнопкой «Поля по всем колонкам». Поле получает подпись по имени колонки.
4. Задайте проверки: «Обязательное поле», длину и «Шаблон (регулярное выражение)» у текста, «Границы значения» у числа, «Границы даты» у даты. «Текст ошибки» покажется вместо стандартного.
5. В «Кнопка отправки» задайте надпись, цвет и вид кнопки. В «После отправки» — переменную для идентификатора новой записи.
6. Проведите связь с выхода формы на экран «Спасибо».

![Элемент «Форма записи»: список и поля формы](https://support.watbot.ru/_media/ru/02-mini-apps/_images/record-form.webp?v=1791781230)

Значения проверяются ещё раз на сервере. Пока есть ошибки, форма остаётся на экране и подсвечивает поля. Тексты ошибок по умолчанию: «Заполните это поле», «Введите число», «Введите дату», «Значение не меньше …», «Значение не больше …», «Не короче … символов», «Не длиннее … символов», «Значение не подходит по формату».

**Ограничения формы:**

- до 50 полей;
- из поля сохраняется до 5000 символов;
- один посетитель создаёт через формы до 60 новых записей в час. Сверх этого — сообщение «Слишком много отправок формы подряд, попробуйте позже.»

## Теги

В приложении два вида тегов.

| | Теги пользователя | Теги контакта |
|---|---|---|
| Чьи | Самого приложения — есть у каждого, кто его открыл, даже без бота | Контакта в чат-боте — те же, что в карточке контакта |
| Чем меняются | Блок «Теги пользователя», вручную в карточке пользователя | Блок «Теги контакта». Нужен контакт бота |
| Где видны | Карточка пользователя в разделе «Пользователи» | Карточка контакта бота |
| Переменная | `appTags` | `contactTags` |

![Блок «Теги пользователя»](https://support.watbot.ru/_media/ru/02-mini-apps/_images/tags-block.webp?v=1791781230)

По тегам работают условия: «Тег пользователя» и «Тег контакта» со сравнениями «содержит теги» и «не содержит теги». Можно перечислить несколько тегов — достаточно одного из них. Теги сравниваются без учёта регистра.

У одного человека — до 500 тегов: новые сверх этого не добавляются.

## Условия

Условия задаются одинаково в блоке «Условие» и в «Условии показа» элемента, области или кнопки шапки.

- «Как объединять»: «Все условия» или «Любое из условий».
- У каждого сравнения — «Что проверяем», «Сравнение» и «Значение». Сравнений — до 20.

![Настройки блока «Условие»: переменная и тег пользователя](https://support.watbot.ru/_media/ru/02-mini-apps/_images/condition.webp?v=1791781230)

| «Что проверяем» | На что смотрит |
|---|---|
| «Переменную» | Любую переменную — её имя указывается в поле «Переменная» |
| «Источник запуска» | Откуда открыто приложение: «Браузер», «С экрана (PWA)», «Telegram», «MAX», «Веб-чат». Сравнения — `=` и `!=` |
| «Параметр ссылки» | То, что было в ссылке после `startapp`: по нему различают источники переходов и акции |
| «Тег контакта» | Теги контакта в чат-боте |
| «Тег пользователя» | Теги приложения |

Сравнения: `=`, `!=`, `>`, `<`, `>=`, `<=`, «содержит», «не содержит», «пусто», «не пусто», «содержит теги», «не содержит теги». «Больше» и «меньше» сравнивают числа, «содержит» — текст без учёта регистра. В «Значение» можно подставить переменную: `{{ имя }}`.

Условие показа по полю этого же экрана срабатывает сразу, пока человек заполняет поле: например, поле «Комментарий» появляется, только когда включён переключатель «Нужна доставка».