Как сконфигурировать пошаговый опросник в боте - Корбот - больше чем конструктор

Формат файла

Файлы конфигурации опросников могут использовать формат .json или .yaml для описания параметров опросника, определения вопросов и возможных ответов. Кодировка файла должна быть utf-8.

Хранение конфигурации

Бот хранит все опросники в базе данных. Вы можете загружать, скачивать и настраивать опросники в административной секции бота. Бот использует поле id структуры конфигурации для идентификации опросника в системе. Обратите внимание, что загрузка уже существующего id в базу данных удалит версию, хранящуюся в базе данных.

Структура объектов

Конфигурация опросника состоит из трех основных разделов:

Корневой раздел
Раздел объектов вопросов
Раздел массива ответов (может присутствовать в каждом вопросе)

Корневой раздел

Корневой раздел должен содержать поля:

«id» — уникальный идентификатор в системе (строка)
«name» — название опросника для отображения в чатах и отчетах (строка)
«enabled» — установите false, чтобы скрыть опросник из всех меню (логическое значение)
«questions» — раздел вопросов (объект)

Необязательные поля:

«start_tip» — сообщение, которое будет отправлено при начале опросника (строка)
«finish_tip» — сообщение, которое будет отправлено при завершении опросника (строка)
«btn_back_enabled» — установите true, чтобы показать кнопку «назад» для вопросов (логическое значение)
«btn_back_text» — текст кнопки «назад» (строка)
«btn_abort_enabled» — установите true, чтобы показать кнопку «отмена» для вопросов (логическое значение)
«btn_abort_text» — текст кнопки «отмена» (строка)
«silent» — установите true, чтобы подавить сообщения о завершении и бесшумно вернуться к предыдущему состоянию (логическое значение)
«command_on_quit» — команда для выполнения при завершении опросника (строка)

Раздел вопросов

Раздел вопросов содержит объекты вопросов. Он должен иметь хотя бы один объект вопроса. Если есть вопрос с именем root, он будет первым вопросом в опроснике, который будет задан. Если вопроса root не существует, первым будет использован первый вопрос в конфигурации.

Имя объекта вопроса используется для обращения к конкретному вопросу в конфигурации.

Каждый объект вопроса состоит из полей:

Обязательные поля:

«question» — текст вопроса для отображения в чате (строка)

Необязательные поля:

«next» — имя следующего вопроса, который будет задан (строка). Если не указано, этот вопрос потребует, чтобы ответ пользователя соответствовал одному из возможных ответов, указанных в поле «answers».
«answers_in_row» — сколько возможных ответов должно отображаться в одном ряду кнопок в чате (число). По умолчанию 2
«answers» — массив разделов возможных ответов
«image» — путь к файлу изображения для отображения с вопросом (строка)
«info» — сообщение для отправки после ответа пользователя на этот вопрос (строка)
«validate» — тип валидации для ввода пользователя (строка, см. раздел Типы валидации)
«manual_input_enabled» — разрешить пользователю вводить произвольный ответ вместо выбора из предопределенных вариантов (логическое значение)
«multiple» — разрешить пользователю выбирать несколько ответов из предопределенных вариантов (логическое значение)
«can_skip» — разрешить пользователю пропустить вопрос с множественным выбором без выбора любого варианта (логическое значение)
«skip_answer_text» — текст для использования, когда пользователь пропускает вопрос с множественным выбором (строка)
«proceed_btn_text» — пользовательский текст для кнопки «продолжить» в вопросах с множественным выбором (строка)
«btn_back_enabled» — переопределить глобальную настройку кнопки «назад» для этого вопроса (логическое значение)
«btn_back_text» — переопределить глобальный текст кнопки «назад» для этого вопроса (строка)
«btn_abort_enabled» — переопределить глобальную настройку кнопки «отмена» для этого вопроса (логическое значение)
«btn_abort_text» — переопределить глобальный текст кнопки «отмена» для этого вопроса (строка)
«join_group» — добавить пользователя в указанную группу при ответе на этот вопрос (строка)
«leave_group» — удалить пользователя из указанной группы при ответе на этот вопрос (строка)

Поля, специфичные для валидации:

«regex» — шаблон регулярного выражения для валидации (строка)
«regex_error» — пользовательское сообщение об ошибке специально для сбоев валидации по регулярному выражению (строка)
«validation_error» — пользовательское сообщение об ошибке для сбоев валидации (строка)
«min_value» — минимальное допустимое значение для валидации целых чисел (число)
«max_value» — максимальное допустимое значение для валидации целых чисел (число)
«max_len» — максимальная допустимая длина текста для валидации длины (число)
«min_date» — минимальная допустимая дата для валидации даты (строка, формат: ГГГГ-ММ-ДД)
«max_date» — максимальная допустимая дата для валидации даты (строка, формат: ГГГГ-ММ-ДД)

Раздел ответов

Раздел ответов — это массив, состоящий из объектов ответов.

Каждый объект ответа состоит из полей:

Обязательные поля:

«text» — текст возможного ответа (строка)

Необязательные поля:

«next» — имя следующего вопроса, который будет задан (строка). Если не указано, будет использоваться соответствующее поле из раздела вопроса
«join_group» — добавить пользователя в указанную группу при выборе этого ответа (строка)
«leave_group» — удалить пользователя из указанной группы при выборе этого ответа (строка)

Типы валидации

Система поддерживает следующие типы валидации:

«integer»

Проверяет, что ввод является целым числом.

Дополнительные поля: min_value, max_value, regex, regex_error, validation_error
Пример:

validate: integer

min_value: 10

max_value: 170

regex: ^\d+0$

regex_error: 'Ошибка! Ограничение скорости должно быть кратно 10 (например: 50, 60, 70)'

validation_error: Укажите корректное ограничение скорости.

«length»

Проверяет, что текстовый ввод не превышает максимальную длину.

Дополнительные поля: max_len, validation_error
Пример:

validate: length

max_len: 300

validation_error: Текст слишком длинный.

«image»

Проверяет, что пользователь отправляет фотографию.

Дополнительные поля: validation_error
Пример:

validate: image

validation_error: Пожалуйста, отправьте фотографию.

«file»

Проверяет, что пользователь отправляет документ/файл.

Дополнительные поля: validation_error
Пример:

validate: file

validation_error: Пожалуйста, отправьте файл.

«location»

Проверяет, что пользователь отправляет свое местоположение.

Дополнительные поля: validation_error
Пример:

validate: location

validation_error: Пожалуйста, отправьте ваше местоположение.

«date»

Проверяет ввод даты с помощью календаря.

Дополнительные поля: min_date, max_date, validation_error
Пример:

validate: date

min_date: 2024-01-01

max_date: 2024-12-31

validation_error: Выберите корректную дату.

Автоматическая валидация по регулярному выражению

Когда в конфигурации вопроса указано поле regex, ввод будет автоматически проверяться по шаблону регулярного выражения независимо от типа валидации. Это применяется ко всем типам валидации и вопросам без явных типов валидации.

Приоритет сообщений об ошибках регулярного выражения:

regex_error — если указано, используется для сбоев валидации по регулярному выражению
validation_error — если regex_error не указано, используется это поле
Системное сообщение по умолчанию — если ни одно не указано

Пример:

question: Укажите координаты (например, 53.205, 38.479)

regex: ^\d{1,2}\.\d{3,},\s?\d{1,2}\.\d{3,}$

regex_error: 'Ошибка! Неверный формат координат. Используйте формат: 53.205, 38.479'

validation_error: 'Ошибка! Неверный формат значения, это должно быть два дробных числа, разделённых запятой.'

Вопросы с множественным выбором

Для вопросов с выбором нескольких ответов:

question: Укажите тип нарушения.

answers:

  - text: Светофор

  - text: Автобусная полоса

  - text: Ремень

multiple: true

can_skip: true

skip_answer_text: (Нет ответа)

proceed_btn_text: Указал

next: direction

Возможности:

multiple: true — включает режим множественного выбора
can_skip: true — разрешает пропуск без выбора
skip_answer_text — текст, используемый при пропуске вопроса
proceed_btn_text — пользовательский текст для кнопки «продолжить»
Ответы отображаются как встроенная клавиатура с флажками
Выбранные ответы объединяются с разделителем «; «

Ручной ввод

Разрешите пользователям вводить произвольные ответы вместо выбора предопределенных вариантов:

question: Укажите комментарий (опционально)

answers:

  - text: Пропустить

manual_input_enabled: true

next: quit

Динамический контент

Вы можете ссылаться на предыдущие ответы в тексте вопроса, используя синтаксис %question_id%:

question: Подтвердите введённое значение: %confirm%

answers:

  - text: Подтвердить

    next: after-answer

  - text: Отмена

    next: quit

Управление группами пользователей

Автоматически управляйте группами пользователей на основе ответов:

question: Выберите ваш статус

answers:

  - text: Студент

    join_group: students

  - text: Преподаватель

    join_group: teachers

    leave_group: students

Управление потоком опросника

Используйте поле «next» для указания следующего вопроса
Используйте «quit» как значение next для завершения опросника (необязательно — опросник также завершится, когда больше нет доступных вопросов)
Если «next» не указано, система попытается найти следующий вопрос по порядку

Прерывание

Опросник может быть прерван:

Отправкой команды /abort
Использованием кнопки отмены (если включена)

Навигация назад

Используйте кнопку «назад» (если включена) для возврата к предыдущему вопросу
Предыдущий ответ удаляется при возврате назад

Форматы файлов

Пример JSON

{

  "id": "example_questionnaire",

  "name": "Пример опросника",

  "enabled": true,

  "start_tip": "Добро пожаловать в опросник!",

  "finish_tip": "Спасибо за заполнение опросника!",

  "btn_back_enabled": true,

  "btn_back_text": "Назад",

  "btn_abort_enabled": true,

  "btn_abort_text": "Отмена",

  "questions": {

    "root": {

      "question": "Как вас зовут?",

      "next": "age"

    },

    "age": {

      "question": "Сколько вам лет?",

      "validate": "integer",

      "min_value": 18,

      "max_value": 100,

      "next": "quit"

    }

  }

}

Пример YAML

id: example_questionnaire

name: Пример опросника

enabled: true

start_tip: Добро пожаловать в опросник!

finish_tip: Спасибо за заполнение опросника!

btn_back_enabled: true

btn_back_text: Назад

btn_abort_enabled: true

btn_abort_text: Отмена

questions:

  root:

    question: Как вас зовут?

    next: age

  age:

    question: Сколько вам лет?

    validate: integer

    min_value: 18

    max_value: 100

    next: quit

Результаты и отчетность

Автоматические возможности

Все результаты опросников сохраняются в базе данных
Результаты могут быть отправлены администраторам через чат
Результаты могут быть отправлены по электронной почте (если настроено)
Результаты включают текст вопроса, ответ пользователя и временную метку
Медиафайлы (изображения, документы) сохраняются и могут быть включены в отчеты

Формат результата

{

  "user": {...},

  "chat_id": {...},

  "questionnaire": "questionnaire_name",

  "begin_date": "2024-01-01T00:00:00Z",

  "finished": true,

  "user_answers": [

    {

      "question": "Как вас зовут?",

      "question_image": null,

      "question_id": "root",

      "answer": "Иван Иванов",

      "date": "2024-01-01T00:00:00Z"

    }

  ]

}

Лучшие практики

Рассмотрите включение маркера «quit» для явного завершения опросника (необязательно — опросник также завершится, когда больше нет доступных вопросов)
Используйте описательные ID вопросов для упрощения обслуживания
Предоставляйте сообщения об ошибках валидации для лучшего пользовательского опыта
Тестируйте поток опросника для избежания тупиковых ситуаций
Используйте manual_input_enabled когда хотите разрешить произвольный текстовый ввод
Рассмотрите использование silent: true для встроенных опросников
Используйте динамический контент (%question_id%) для вопросов подтверждения
Группируйте связанные вопросы логически в вашей конфигурации

Обработка ошибок

Недействительные конфигурации опросников будут отклонены при импорте
Отсутствующие вопросы вызовут ошибки навигации
Сбои валидации покажут сообщения об ошибках и повторят вопросы
Система автоматически обрабатывает хранение и очистку медиафайлов

Примечание: Обязательно правильно конструируйте конфигурацию опросника, чтобы избежать тупиковых ситуаций (когда следующий вопрос не указан и больше нет доступных вопросов в конфигурации).