Формы

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

📝 Назначение

Формы используются для:

• Регистрации пользователей (имя, email, телефон)
• Сбора заказов (товар, количество, адрес)
• Проведения опросов и голосований
• Обратной связи и заявок
• Любых сценариев, где нужно получить несколько данных в строгой последовательности

Ключевые возможности:

• Последовательный сбор данных (поле за полем)
• Валидация вводимых данных (email, телефон, число, regex)
• Поддержка различных типов полей (текст, выбор, медиа, дата)
• Условное отображение полей
• Автоматическое сохранение результатов
• Кастомные сообщения об ошибках

💡 Совет: Используйте формы вместо длинных диалогов с пользователем — они обеспечивают предсказуемый порядок и формат данных.

Как это работает

⚠️ Важно: Форму можно запустить только в личном чате с ботом. Запустить форму для другого пользователя удалённо нельзя.

Создание формы

Шаг 1: Перейдите в раздел

/adm → Формы → Добавить

Шаг 2: Настройте основные параметры

💡 Совет: Лимит интервала полезен, чтобы пользователи не спамили запусками формы. Например, установите 60 — одна форма в минуту.

Шаг 3: Добавьте поля

Нажмите «Добавить поле» и настройте его.

Типы полей формы

Настройка поля

Общие настройки

Валидация (для текстовых полей)

Настройки для поля «Выбор»

Настройки для поля «Дата»

Триггеры формы

У каждой формы есть встроенные триггеры, которые срабатывают на разных этапах.

Доступ к результатам

После заполнения формы данные доступны в переменной:

${form.fields.ключ}

где ключ — значение, указанное в настройках поля.

Примеры:

Пример использования результата

В триггере «Финиш формы»:

1. GetVarCloud → загружаем текущие данные пользователя
2. SetVarCloud → сохраняем имя: ${form.fields.name}
3. SetVarCloud → сохраняем телефон: ${form.fields.phone}
4. SendMessage → Спасибо, ${form.fields.name}! Мы свяжемся с вами по номеру ${form.fields.phone}.

Работа с медиа в формах

Поля типа «Фото», «Видео», «Аудио», «Файл» возвращают объект с file_id. Чтобы отправить этот файл позже, используйте макрос !{media}:

!{media|path: ${form.fields.photo}}

Пример в триггере «Финиш формы»:

1. SetVarCloud → сохраняем фото: ${form.fields.photo}  # сохраняем как есть
2. SendMessage → "Ваше фото получено!"
3. SendMessage → !{media|path: ${form.fields.photo}}  # пересылаем фото пользователю

Условное отображение полей

Вы можете показывать или скрывать поля в зависимости от предыдущих ответов. Для этого используйте триггер «Перед полем».

Пример: Показывать поле «Адрес доставки» только если пользователь выбрал «Доставка» в предыдущем поле.

В триггере «Перед полем» для поля «Адрес доставки»:

1. TriggerFolder с условием: String → ${form.fields.delivery_type} = "Доставка"
   → (условие true) — поле показывается
   → (условие false) — поле скрывается с помощью Exit

Доступные реакции для работы с формами

Пример: форма регистрации

Задача: Собрать контактные данные нового пользователя.

Поля формы

Триггер «Финиш формы»

Реакция 1: SetVarCloud
  → Тип: person
  → Название: user_name
  → Значение: ${form.fields.name}

Реакция 2: SetVarCloud
  → Тип: person
  → Название: user_email
  → Значение: ${form.fields.email}

Реакция 3: SetVarCloud
  → Тип: person
  → Название: user_phone
  → Значение: ${form.fields.phone}   # если поле не было заполнено — пусто

Реакция 4: SendMessage
  → Текст: ✅ Регистрация завершена!

Реакция 5: SendMessage (в технический чат)
  → Текст: Новый пользователь: ${form.fields.name}, ${form.fields.email}

Запуск формы

Обработчик команды /register:

Реакция 1: StartForm
  → Форма: registration

⚠️ Частые ошибки и их решение

Ошибка 1: Форма не запускается

Причина: Пользователь уже находится в активной форме. Решение: У пользователя может быть только одна активная форма. Используйте CancelForm перед запуском новой формы.

Ошибка 2: Поле не проходит валидацию, но ошибка не показывается

Причина: Триггер «Ошибка поля» не настроен. Решение: Добавьте в триггер «Ошибка поля» реакцию SendMessage с текстом ошибки. Используйте ${form.error} для отображения текста ошибки.

Ошибка 3: Данные не сохраняются

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

Ошибка 4: Неправильный доступ к полю выбора

Причина: Использование ${form.fields.choose} для одиночного выбора. Решение: Для одиночного выбора используйте ${form.fields.choose.0}. Для множественного — ${form.fields.choose} (это массив).

Ошибка 5: Пользователь может вернуться к заполненному полю

Причина: Кнопка «Назад» не скрыта. Решение: Включите опцию «Скрыть кнопку "Назад"» в настройках поля, если возврат нежелателен.

Ошибка 6: Медиа-файл не сохраняется

Причина: Медиа-файл сохраняется как объект, а не как строка. Решение: Сохраняйте ${form.fields.photo} как есть (это объект с file_id). Для отправки используйте !{media|path: ${form.fields.photo}}.

Сравнение форм и обычных диалогов

💡 Совет: Используйте формы, когда нужно собрать 3+ полей. Для 1–2 полей достаточно обычного диалога.

🔗 Связанные разделы

🔗 Быстрая навигация

• Вверх
• Создание формы
• Типы полей
• Настройка поля
• Триггеры формы
• Доступ к результатам
• Примеры
• Частые ошибки
• Связанные разделы