К содержимому
Настройка

Формы и поля

Обновлено

Сначала получите словарь

Перед изменениями агенту нужно вызвать requests_get_schema. Типы полей и режимы форм берутся из установленного приложения «Заявки», включая расширения, добавленные его плагинами. Используйте возвращённые идентификаторы, а не предполагаемые названия типов.

Затем вызовите requests_get_form для существующей формы. Ответ содержит поля с id, type, required, role, sort и settings.

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

Последовательность работы:

  1. requests_create_form — создать форму с name; описание, режим и порядок необязательны. По умолчанию режим — standard.
  2. requests_add_field — добавить поля, используя возвращённый form_id и типы из словаря.
  3. requests_set_form_settings — записать необходимые параметры формы.
  4. requests_get_form — проверить результат.
Получи словарь типов полей. Создай форму «Запись на замер»
с обязательным телефоном и полем даты.
Покажи идентификаторы формы и полей и её текущие настройки.

Обычное создание формы не гарантирует, что она выключена: отсутствие параметра active трактуется как включённое состояние. Копия через requests_clone_form и форма после requests_import_form создаются выключенными.

Как адресуются значения

В аргументе fields ключом служит field_id из requests_get_form. Имя поля тоже принимается, если оно однозначно в пределах формы; регистр и пробелы по краям не учитываются.

Неизвестный идентификатор, неизвестное имя или несколько полей с одинаковым именем приводят к ambiguous_field. Возьмите идентификатор из возвращённого перечня form_fields.

Роли name, email, phone, company, comment задают смысл поля для обработки заявки. При добавлении или правке поля роль передаётся внутри settings, ключом role. Поля типов email и phone могут получать соответствующую роль без явного назначения. На чтении роль приходит отдельно от типа.

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

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

requests_update_field изменяет переданные свойства поля. Настройки поля передаются объектом settings; перед изменением прочитайте текущие настройки и включите в объект те, которые нужно сохранить.

Условная видимость передаётся ключом visible_when внутри settings. Оно ссылается на другое поле той же формы и проверяется средствами приложения. Формат содержит field, operator и, для операторов сравнения, value. Для eq, neq и contains значение должно быть непустым. При неверном условии возвращается invalid_param с подсказкой о допустимых операторах.

Значение visible_when: null или пустой массив снимает условие. Ссылка поля на само себя не принимается.

requests_sort_fields получает form_id и полный массив field_ids в нужном порядке. Передавайте каждый идентификатор один раз. Удаление поля требует confirm: true; старые значения сохраняются в заявках с отметкой об удалённом поле.

Изменение настроек формы

requests_set_form_settings принимает form_id и объект settings. Переданные ключи записываются, остальные не затрагиваются. Пустой объект не принимается. Описанные ключи, их типы и назначение доступны в form_settings ответа requests_get_schema.

Например, технический ключ active управляет приёмом заявок, а search_contact и create_contact — поиском и созданием контакта. Это параметры формы приложения «Заявки», а не настройки плагина MCP.

Список ключей в словаре не исчерпывающий: инструмент записи допускает произвольные имена. Успешный ответ о сохранении неизвестного ключа не подтверждает, что приложение использует его. Агенту следует опираться на словарь и текущую форму.

Секреты при чтении

requests_get_form заменяет непустые секретные настройки на ***, а их имена перечисляет в masked_settings. В частности, скрываются api_token и telegram_bot_token; фильтр также распознаёт секреты по имени настройки. Адреса получателей уведомлений остаются видимыми.

Записать новый секрет через requests_set_form_settings можно. Не отправляйте *** обратно вместо существующего токена: это маска ответа, а не исходное значение. При частичной правке исключите скрытые ключи, если менять их не нужно.

Перенос формы между сайтами

  1. На исходной установке вызовите requests_export_form с form_id.
  2. Получите объект export, включая список omitted_settings.
  3. Передайте JSON этого объекта целиком строкой в аргументе file инструмента requests_import_form на целевой установке.
  4. Проверьте warnings и созданную форму через requests_get_form.
  5. Заполните исключённые настройки, проверьте получателей и только затем включите приём заявок.

Существующие формы при импорте не изменяются. Заявки в эту выгрузку не входят. Токены, ключи и локальные параметры, включая получателей уведомлений, исключаются механизмом переноса приложения. Сверяйтесь с фактическим списком omitted_settings.

Проверка уведомлений

requests_test_notification принимает form_id, channel и confirm: true. Каналы: email, sms, push, telegram.

Сообщение собирается на тестовых значениях без создания заявки и уходит настоящим получателям из сохранённых настроек формы. Чтобы проверить другой адрес, сначала измените настройки формы. Ошибка канала возвращается как channel_failed; подробности находятся в error_message и details.