Инструменты MCP

Инструменты: формат ответа, права и тарифы

Инструменты (Tools)

Tools — действия, которые выполняются на стороне WebAsk по запросу ИИ-модели.

Формат ответа инструментов

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

Клиенты (Claude, Cursor, Codex, mcp-remote) передают модели только content, поэтому доп. ключи продублированы в нём вторым блоком {"type": "text", "text": "<JSON доп. ключей>"} — и у успеха, и у ошибки. Сами доп. ключи остаются на верхнем уровне. Ответ без доп. ключей — один блок. Инструменты, отдающие JSON ресурса (структура опроса, ответы, отчёты), кладут его прямо в первый блок, второго нет.

Ответы на JSON-RPC запросы (результаты и ошибки методов) кодируются в UTF-8 без экранирования: кириллица и / идут как есть, а не \uXXXX и \/. Ранние отказы транспорта (авторизация, тариф, версия протокола) — короткие английские сообщения, их кодирование не менялось.

Примеры ниже показывают полную оболочку ответа. Значения внутри quiz, item и других данных иллюстративны: их состав зависит от инструмента. Если дополнительные поля показаны рядом с content, тот же объект данных находится JSON-строкой во втором текстовом блоке. Разбирайте JSON из content, а не текст сообщения об успехе.

Успех с дополнительными полями:

{
  "content": [
    {"type":"text","text":"Опрос #123 переименован в \"Новое название\"."},
    {"type":"text","text":"{\"quiz_id\":123,\"name\":\"Новое название\"}"}
  ],
  "isError":false,
  "quiz_id":123,
  "name":"Новое название"
}

Ошибка с деталями проверки:

errors ниже иллюстрирует ошибки логики; конкретный текст зависит от нарушения. Данные доступны и рядом с content, и во втором блоке.

{
  "content": [
    {"type":"text","text":"Логика не сохранена: есть ошибки."},
    {"type":"text","text":"{\"errors\":[\"Переход ссылается на отсутствующий вопрос.\"]}"}
  ],
  "isError":true,
  "errors":["Переход ссылается на отсутствующий вопрос."]
}

Инструмент, возвращающий JSON ресурса:

У get_quiz_structure данные находятся в первом блоке; widgets, conditions и остальные поля ресурса не дублируются на верхнем уровне. Пример содержит сокращённые иллюстративные данные ресурса.

{
  "content":[{"type":"text","text":"{\"id\":123,\"widgets\":{\"ids\":[],\"entities\":{}},\"conditions\":{},\"extra_fields\":[]}"}],
  "isError":false
}

Если JSON ресурса содержит строковое error, инструмент возвращает isError: true; сообщение об ошибке также остаётся JSON в первом блоке.

Ошибка без дополнительных полей:

{
  "content": [{"type": "text", "text": "Ошибка валидации: Поле quiz_id обязательно для заполнения."}],
  "isError": true
}

Права и тарифы

Инструменты записи проверяют то же, что и интерфейс конструктора.

Доступ к MCP по тарифу — опция mcp_access. Она есть на всех тарифах, включая бесплатный. Воркспейс без действующего заказа считается бесплатным и получает ответ бесплатного тарифа; заказ при проверке не создаётся.

Права участника воркспейса. Владелец воркспейса может выдать участнику урезанные права. Если права на действие нет, инструмент отвечает отказом, из которого видно, что делать дальше:

• имя права и его код — Недостаточно прав: для этого действия нужно право «Удаление опросов» (delete_quiz);
• значение у роли: allowed (разрешено, но объект в закрытой папке), partially — только свои объекты, причём над чужим объектом это названо прямо, forbidden — запрещено, не задано — считается запрещённым;
• отличие по папке, если для папки объекта у роли стоит своё значение;
• причина, из-за которой права не действуют вовсе: приглашение не принято, почта не подтверждена, не участник;
• кто может право выдать: владелец или участник с member_crud, инструменты save_workspace_role и set_workspace_member_role.

Свои права по всем пространствам ассистент читает заранее из user://me (workspaces[].access), права другого участника — get_workspace_member_access. Расчёт там тот же, что у проверки при вызове.

Тарифный отказ называет закрытую возможность и дописывает, где посмотреть текущий тариф (get_workspace_tariff — лимиты и возможности) и что дают другие (get_tariff_list); сменить тариф может владелец или участник с правом payment.

Таблица прав по инструментам:

Правка вопросов, логики, текстов, переменных и скрытых опций требует edit_quiz. Доступ к опросу, пространство токена и права папки проверяются отдельно. Для структуры, логики, текстов, публикации и восстановления версии дополнительно действует блокировка оплаченной кампанией за респондентов. Отказ по праву не устраняется повторением запроса: сначала уточните роль и доступы. Проверка edit_quiz не заменяет settings, theme, integrations или files_upload там, где инструмент требует их.

update_quiz_settings требует settings. При передаче полей счётчиков и пикселей дополнительно проверяются integrations и тариф соответствующей интеграции. Инструменты писем опроса проверяют доступ к опросу и свои условия инициализации/тарифа; право settings им не следует приписывать по аналогии с booking.

Тарифные ограничения. Проверяются до выполнения действия:

Опросы: создание, публикация, версии

Примеры ответов показывают оболочку content/isError и иллюстративные данные. Дополнительные поля ответа дублируются JSON-строкой вторым текстовым блоком. Точные текущие id и состав опроса читайте из соответствующих ресурсов.

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

create_quiz

Создаёт новый опрос.

При чтении каталога через get_quiz_list можно выбрать type: "regular" (отдельная страница опроса) или type: "micro" (микроопрос на странице другого сайта). Пропуск type или null возвращает оба типа; это фильтр чтения, а не параметр create_quiz. Подробности — в инструментах чтения. Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Опрос успешно создан (ID: 1)."
    },
    {
      "type": "text",
      "text": "{\"quiz\":{\"id\":1,\"workspace_id\":5,\"answer_count\":0,\"visits\":{\"visit\":0,\"u_visit\":0},\"ssid\":\"...\",\"shared\":false,\"isPublished\":false,\"is_archive\":false,\"is_template\":false,\"name\":\"Новый опрос\",\"virtual_id\":null,\"url_preview\":\"https://...\",\"url_shared\":\"https://...\",\"project\":null,\"quiz_data\":{\"ids\":[],\"entities\":{}},\"conditions\":null,\"settings\":{\"lang\":\"ru\",\"show_progressbar\":true,\"show_navigate\":true,\"numeration\":false,\"theme_id\":1,\"...\":\"...\"},\"info\":{\"info_title\":\"\",\"description\":\"\",\"og_image\":null,\"favicon\":null},\"integrations\":{}}}"
    }
  ],
  "isError": false,
  "quiz": {
    "id": 1,
    "workspace_id": 5,
    "answer_count": 0,
    "visits": {
      "visit": 0,
      "u_visit": 0
    },
    "ssid": "...",
    "shared": false,
    "isPublished": false,
    "is_archive": false,
    "is_template": false,
    "name": "Новый опрос",
    "virtual_id": null,
    "url_preview": "https://...",
    "url_shared": "https://...",
    "project": null,
    "quiz_data": {
      "ids": [],
      "entities": {}
    },
    "conditions": null,
    "settings": {
      "lang": "ru",
      "show_progressbar": true,
      "show_navigate": true,
      "numeration": false,
      "theme_id": 1,
      "...": "..."
    },
    "info": {
      "info_title": "",
      "description": "",
      "og_image": null,
      "favicon": null
    },
    "integrations": {}
  }
}

rename_quiz

Переименовывает существующий опрос. Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Опрос #1 переименован в \"Новое название опроса\"."
    },
    {
      "type": "text",
      "text": "{\"quiz_id\":1,\"name\":\"Новое название опроса\"}"
    }
  ],
  "isError": false,
  "quiz_id": 1,
  "name": "Новое название опроса"
}

duplicate_quiz

Создаёт копию опроса со всеми данными и версиями. Счётчики и пиксели (Google Analytics, Яндекс.Метрика, VK, Facebook) копируются вместе со своими интеграциями: в копии они видны и отключаются через manage_quiz_analytics. Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Опрос #1 успешно дублирован (новый ID: 2)."
    },
    {
      "type": "text",
      "text": "{\"quiz\":{\"id\":2,\"name\":\"Копия опроса\",\"url_shared\":\"https://...\",\"is_published\":false,\"created_at\":\"2024-01-15T12:00:00.000000Z\",\"updated_at\":\"2024-01-15T12:00:00.000000Z\"}}"
    }
  ],
  "isError": false,
  "quiz": {
    "id": 2,
    "name": "Копия опроса",
    "url_shared": "https://...",
    "is_published": false,
    "created_at": "2024-01-15T12:00:00.000000Z",
    "updated_at": "2024-01-15T12:00:00.000000Z"
  }
}

archive_quiz

Архивирует или разархивирует опрос. Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Опрос архивирован."
    },
    {
      "type": "text",
      "text": "{\"quiz_id\":1,\"archive_at\":\"2024-01-15 12:00:00\",\"is_archived\":true}"
    }
  ],
  "isError": false,
  "quiz_id": 1,
  "archive_at": "2024-01-15 12:00:00",
  "is_archived": true
}

delete_quiz

Удаляет опрос (мягкое удаление, с возможностью восстановления). Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Опрос #1 удален."
    },
    {
      "type": "text",
      "text": "{\"quiz_id\":1}"
    }
  ],
  "isError": false,
  "quiz_id": 1
}

restore_quiz

Возвращает удалённый опрос из корзины — с вопросами, логикой и ответами.

Опрос снова занимает место в тарифном лимите, поэтому при исчерпанном лимите возврат не пройдёт. Живой и чужой опрос в возврат не попадают, о пропущенных приходит skipped_quiz_ids. Архив — другое: его снимает archive_quiz.

publish_quiz

Публикует опрос: текущая локальная версия становится публичной.

Требуется право edit_quiz в дополнение к доступу к опросу. Сохранение структуры или логики само по себе не публикует черновик.

Опрос под оплаченной кампанией за респондентов не публикуется и не откатывается к прежней версии — инструмент отказывает и называет причину. Подробности — в tools-quiz-content.md.

Черновик должен укладываться в тариф целиком: если вопросов больше лимита тарифа или есть хоть один вопрос недоступного типа, инструмент отказывает (isError: true) и называет лимит либо типы и id вопросов. Ничего не публикуется — прежняя публичная версия продолжает работать и принимать ответы. Подсчёт вопросов и ключи типов — как в update_quiz_widgets (tools-quiz-content.md). restore_quiz_version состав не проверяет: он возвращает версию в черновик, а публикуется она только через publish_quiz. Черновик после AI-сборки (generate_ai_quiz) при записи тариф не сверяет, поэтому может не опубликоваться по тем же причинам.

Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Опрос #1 успешно опубликован."
    },
    {
      "type": "text",
      "text": "{\"quiz\":{\"id\":1,\"workspace_id\":5,\"answer_count\":0,\"name\":\"Мой опрос\",\"url_shared\":\"https://...\",\"isPublished\":true,\"quiz_data\":{\"ids\":[\"uuid-1\"],\"entities\":{\"uuid-1\":{\"type\":\"question\",\"title\":\"Вопрос\"}}},\"conditions\":{},\"settings\":{\"lang\":\"ru\",\"theme_id\":1,\"...\":\"...\"},\"info\":{},\"integrations\":{}}}"
    }
  ],
  "isError": false,
  "quiz": {
    "id": 1,
    "workspace_id": 5,
    "answer_count": 0,
    "name": "Мой опрос",
    "url_shared": "https://...",
    "isPublished": true,
    "quiz_data": {
      "ids": [
        "uuid-1"
      ],
      "entities": {
        "uuid-1": {
          "type": "question",
          "title": "Вопрос"
        }
      }
    },
    "conditions": {},
    "settings": {
      "lang": "ru",
      "theme_id": 1,
      "...": "..."
    },
    "info": {},
    "integrations": {}
  }
}

move_quiz

Перемещает опрос в другую папку пользователя. Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Опрос перемещен в папку #5."
    },
    {
      "type": "text",
      "text": "{\"quiz_id\":1,\"folder_id\":5}"
    }
  ],
  "isError": false,
  "quiz_id": 1,
  "folder_id": 5
}

make_quiz_template

Создаёт шаблон на основе текущего опроса. Счётчики и пиксели (Google Analytics, Яндекс.Метрика, VK, Facebook) в шаблон не переносятся; исходный опрос не меняется. Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Шаблон успешно создан."
    },
    {
      "type": "text",
      "text": "{\"quiz_id\":1}"
    }
  ],
  "isError": false,
  "quiz_id": 1
}

get_quiz_versions

Показывает историю публикаций опроса: каждая публикация оставляет снимок.

Черновик в список не попадает — это текущее состояние, а не история. Снимок с is_live — тот, который сейчас видят респонденты.

restore_quiz_version

Возвращает содержимое прежнего снимка в черновик — откат неудачной правки.

Требуется edit_quiz; оплаченная кампания за респондентов блокирует откат. Восстановление не снимает необходимость последующей публикации.

Респондентов откат сразу не касается: живая версия остаётся прежней, пока опрос не опубликуют заново (publish_quiz). В ответе приходит needs_publish: true.

Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Версия восстановлена в черновик. Чтобы её увидели респонденты, опубликуйте опрос."
    },
    {
      "type": "text",
      "text": "{\"quiz_id\":42,\"restored_from_version_id\":128,\"live_version_id\":128,\"needs_publish\":true}"
    }
  ],
  "isError": false,
  "quiz_id": 42,
  "restored_from_version_id": 128,
  "live_version_id": 128,
  "needs_publish": true
}

generate_ai_quiz

Запускает AI-генерацию опроса по пользовательскому описанию. Использует тот же backend flow, что и встроенное создание AI-опроса в приложении: модель сама собирает структуру, виджеты и (опционально) логику переходов. Структура ответа (успех):

{
  "content": [{"type": "text", "text": "AI-опрос успешно создан."}],
  "isError": false
}

get_workspace_templates

Собственные шаблоны аккаунта — те опросы, что сделали шаблонами через make_quiz_template.

Это не общий каталог сервиса, его ищет search_quiz_templates. Возвращённый id принимает create_quiz_from_template наравне с каталожным.

search_quiz_templates

Ищет опрос в каталоге готовых. Каталог собран на ru и en — других языков в нём нет.

Без query возвращает каталог целиком. Отдаёт template_id, название и метки — без оформления, чтобы ответ оставался читаемым.

create_quiz_from_template

Создаёт свой опрос из шаблона каталога — с вопросами, логикой и оформлением.

Личная тема автора шаблона копируется в аккаунт, чтобы опрос не ссылался на чужую запись. Счётчики и пиксели шаблона в опрос не переносятся, даже если шаблон сохранили с ними раньше. Опрос создаётся черновиком (needs_publish: true). Скопировать по template_id произвольный чужой опрос нельзя: берутся только те, что лежат в каталоге.

Содержимое и структура опроса

Правка структуры, текстов и логики требует доступа к опросу и права edit_quiz. Она меняет черновик; для показа респондентам нужна отдельная публикация. Настройки требуют settings, загрузка медиа — files_upload и edit_quiz. Примеры ответов показывают оболочку и иллюстративные данные: дополнительные поля дублируются JSON-строкой во втором блоке content.

Содержимое и структура опроса

Заморозка опроса кампанией. Пока по опросу идёт оплаченная кампания за респондентов, его состав менять нельзя: респонденты проходят то, что оплачено и промодерировано. update_quiz_widgets, update_quiz_texts, update_quiz_logic, а также publish_quiz и restore_quiz_version из tools-quiz-lifecycle.md в этом случае отказывают с пояснением про кампанию. update_quiz_settings, интеграции, темы и работа с ответами остаются доступны — так же, как в конструкторе. До оплаты кампании правки открыты: сумма пересчитывается перед платежом. Замок снимается сам по завершении кампании.

update_quiz_widgets

Сохраняет структуру виджетов опроса. Используется для изменения/добавления любых элементов формы. Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Структура виджетов опроса успешно обновлена."
    },
    {
      "type": "text",
      "text": "{\"quiz\":{\"id\":1,\"workspace_id\":5,\"answer_count\":0,\"name\":\"Мой опрос\",\"url_shared\":\"https://...\",\"isPublished\":false,\"quiz_data\":{\"ids\":[\"a1b2c3d4-...\"],\"entities\":{\"a1b2c3d4-...\":{\"type\":\"question\",\"title\":\"Текст вопроса\",\"...\":\"...\"}}},\"conditions\":{},\"settings\":{\"lang\":\"ru\",\"theme_id\":1,\"show_progressbar\":true,\"...\":\"...\"},\"info\":{},\"integrations\":{}}}"
    }
  ],
  "isError": false,
  "quiz": {
    "id": 1,
    "workspace_id": 5,
    "answer_count": 0,
    "name": "Мой опрос",
    "url_shared": "https://...",
    "isPublished": false,
    "quiz_data": {
      "ids": [
        "a1b2c3d4-..."
      ],
      "entities": {
        "a1b2c3d4-...": {
          "type": "question",
          "title": "Текст вопроса",
          "...": "..."
        }
      }
    },
    "conditions": {},
    "settings": {
      "lang": "ru",
      "theme_id": 1,
      "show_progressbar": true,
      "...": "..."
    },
    "info": {},
    "integrations": {}
  }
}

При ошибке структуры виджетов дополнительно возвращается массив errors (список строк с описанием несоответствий).

Тариф. Сохранение отказывает (isError: true, структура не меняется), если опрос становится «хуже» сохранённого черновика:

• вопросов больше лимита тарифа (widgets_count) и больше, чем в черновике — текст называет лимит и сколько получилось бы;
• появился вопрос недоступного на тарифе типа, которого в черновике не было (новый id или вопрос сменил тип) — текст называет типы и id вопросов.

Опрос, переставший укладываться в тариф после перехода на меньший, остаётся редактируемым: тексты менять и вопросы удалять можно. Число вопросов — id из ids без welcome/submit плюс вопросы внутри групп (группа тоже считается). Ключ типа: у choice — choice-media (картинки), choice-multiple (choiceMultiple), иначе choice-single; у smile-rating — rating; у остальных — сам type; типа нет в тарифе — он доступен. Экраны (welcome, submit, finish, screenout) по типу не проверяются. Число вопросов в группах считается только у групп из ids.

AI-сборка опроса (кабинет, generate_ai_quiz, API v3 quiz/ai) пишет черновик через внутренний вызов этого инструмента, и при записи тариф не сверяется: генератор может поставить тип, недоступный на тарифе, или больше вопросов, чем лимит. Такой черновик сохраняется, но publish_quiz его не опубликует, пока лишнее не убрано. То же правило действует в API v3, см. ошибки.

Запись идёт всей структурой целиком. Внутри виджета можно передать только изменённые поля — остальные не затрутся. Но состав виджетов передаётся полностью: каждый id из ids должен быть в entities, а виджет, которого нет в ids, из опроса удаляется. Поэтому правка одного поля — это три шага:

1. get_quiz_structure(quiz_id) — получить widgets.ids и widgets.entities;
2. поправить нужное поле в нужной сущности;
3. update_quiz_widgets(quiz_id, ids, entities) — вернуть структуру обратно.

Структуру, полученную чтением, можно возвращать записью как есть: ничего вычищать из неё не нужно. Исключение — значения, которые не проходят проверки ниже (например, размер поля вне границ): такой вызов отклоняется целиком, и значение нужно исправить.

Размеры полей ввода

Размер задаётся в пикселях, а не в процентах. Границы те же, что у ручки растягивания в конструкторе:

• Значение вне границ отклоняет весь вызов до сохранения. В errors приходят поле, значение, допустимый диапазон и значение по умолчанию.
• У нового виджета поле размера можно не передавать: встанет значение по умолчанию.
• У уже сохранённого виджета пропуск поля ничего не меняет, потому что остаётся прежнее значение. Чтобы вернуть стандартный размер, поле передают явно, со значением по умолчанию.
• Размер проверяется только у типа, которому поле принадлежит. Например, inputWidth у виджета choice не проверяется.

Экраны опроса

Экрана благодарности в опросе по умолчанию нет. Правка полей submit его не создаёт — нужен отдельный виджет finish.

Спецответы вместо обычных вариантов

«Другое / Свой вариант», «Затрудняюсь ответить» и «Ничего из перечисленного» — это настройки виджета, а не пункты списка вариантов:

Такой пункт, добавленный в choiceTextEntities / dropdownEntities руками, не даёт поля свободного ввода, не снимает остальные отметки, не попадает в отдельные показатели отчёта (hardToAnswerCount, hardToAnswerPercent) и перемешивается вместе с обычными вариантами. Если настройка при этом включена — респондент видит два одинаковых пункта.

Инструмент такие подписи не запрещает (бывают и осознанные варианты ответа), но возвращает предупреждение в массиве warnings.

Проверка результата

Ответ содержит ключ saved с фактическим составом опроса после записи — по нему сверяется, что изменение применилось, без повторного чтения структуры:

{
  "content": [
    {
      "type": "text",
      "text": "Структура виджетов опроса успешно обновлена. Сохранено виджетов: 5. Состав: welcome x1, choice x2, finish x1, submit x1."
    },
    {
      "type": "text",
      "text": "{\"saved\":{\"widgets\":5,\"types\":{\"welcome\":1,\"choice\":2,\"finish\":1,\"submit\":1}},\"warnings\":[\"Виджет ...: вариант «Другое» повторяет включённый спецответ (choiceTextOther) ...\"],\"quiz\":{\"...\":\"...\"}}"
    }
  ],
  "isError": false,
  "saved": {
    "widgets": 5,
    "types": {
      "welcome": 1,
      "choice": 2,
      "finish": 1,
      "submit": 1
    }
  },
  "warnings": [
    "Виджет ...: вариант «Другое» повторяет включённый спецответ (choiceTextOther) ..."
  ],
  "quiz": {
    "...": "..."
  }
}

update_quiz_texts

Сохраняет пользовательские тексты кнопок и интерфейсных элементов опроса. (Требуется платный тариф). Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Пользовательские тексты опроса успешно обновлены."
    },
    {
      "type": "text",
      "text": "{\"message\":\"OK\"}"
    }
  ],
  "isError": false,
  "message": "OK"
}

update_quiz_settings

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

{
  "content": [
    {
      "type": "text",
      "text": "Настройки опроса обновлены."
    },
    {
      "type": "text",
      "text": "{\"updated\":[\"name\",\"lang\"]}"
    }
  ],
  "isError": false,
  "updated": [
    "name",
    "lang"
  ]
}

Пример частичного изменения настроек теста — объект arguments. Пропущенные настройки сохраняются; эти значения показывают выбранный сценарий, а не значения по умолчанию:

{
  "quiz_id":123,
  "correct_answers":true,
  "limit_answer_count_mode":"completed_no_screenout",
  "question_timer_mode":"all_enabled",
  "question_timer_seconds":30,
  "question_timer_button_mode":"all_enabled",
  "question_lock_answer_mode":"all_enabled"
}

update_quiz_logic

Сохраняет логические условия, переходы и правила по баллам. Формируется на основе UUID виджетов. Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Логика опроса успешно обновлена."
    },
    {
      "type": "text",
      "text": "{\"quiz\":{\"id\":1,\"name\":\"Мой опрос\",\"quiz_data\":{\"ids\":[],\"entities\":{}},\"conditions\":{\"defaultConditions\":{},\"savedLogic\":{}},\"settings\":{},\"info\":{}}}"
    }
  ],
  "isError": false,
  "quiz": {
    "id": 1,
    "name": "Мой опрос",
    "quiz_data": {
      "ids": [],
      "entities": {}
    },
    "conditions": {
      "defaultConditions": {},
      "savedLogic": {}
    },
    "settings": {},
    "info": {}
  }
}

При редактировании существующего опроса сохраняйте старую карту, если задача не требует её изменения. Непереданный savedScoring сохраняется; переданный заменяет эту карту целиком. Не преобразовывайте старые правила в новый формат автоматически.

Все карты необязательны. Переданная карта заменяет прежнюю целиком, а не дополняет её по UUID: отправка savedLogic только с одним вопросом удалит из этой карты прежние записи остальных вопросов. Непереданные карты сохраняются; перед объединением старые ссылки на удалённые вопросы очищаются. Это правило также действует для defaultConditions, savedInlineGroupLogic, savedScoring и multiLogicFlags. Пустой объект {} очищает именно переданную карту.

Для изменения одного правила:

1. Получите get_quiz_structure с quiz_id; в conditions находятся карты текущего черновика, а в widgets — реальные UUID вопросов и вариантов.
2. Измените нужную запись в полученной карте, сохранив остальные записи этой карты.
3. Передайте quiz_id и полную изменённую карту. Другие карты можно опустить. Проверьте isError, детали errors и предупреждения warnings; только после проверки публикуйте.

Очистка всей условной логики — отдельное намеренное действие:

{"quiz_id":123,"savedLogic":{}}

Группы и условия savedLogic

Операторы условий (option.id)

Оператор задаёт способ сравнения ответа или другого значения. Номер передаётся целым числом в option.id. Идентификаторы вопросов, вариантов ответа и строк матрицы берутся из get_quiz_structure.

Особенности файлов и ранжирования. Для file сохраняйте код состояния в answer.optionId: "12" — файл загружен, "13" — не загружен. Это значения, предлагаемые конструктором; проверенный новый рендерер также принимает "11" для наличия ответа. Он определяет состояние файла по answer.optionId, поэтому одного option.id, даже 11, недостаточно. При редактировании берите пару option/answer из полученной структуры; базовые и legacy-операторы перечислены ниже.

ID 21/22 обозначают «выше/ниже» в редакторе. В проверенном локальном коде нового рендерера обработчик ранжирования не различает option.id и сравнивает только точную позицию. Исполнение этих сравнений на целевой версии нужно проверить в предпросмотре; успешное сохранение правила не подтверждает его поведение при прохождении.

Какие операторы выбирать для нового правила

Базовые наборы ниже соответствуют операторам, предлагаемым конструктором. У конкретного вопроса дополнительные операторы зависят от его настроек. Сохранённые старые правила могут содержать другие совместимые операторы — это не основание предлагать их для нового правила.

Дополнительные операторы:

• 23 появляется, если тип вопроса поддерживает «Затрудняюсь ответить» и включён hardToAnswer.
• 24 применяется для dropdown или текстового choice при включённом noneOfAbove.
• 25/26 применяются при включённом abEnabled; в answer.optionId передаётся идентификатор A/B-варианта из структуры.
• Для матричных и других составных вопросов передавайте специфические данные, описанные в таблице полей условия: matrixData, allocationData, semanticDifferentialData.

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

Пример: «значение шкалы меньше 10»

Это одно условие, которое нужно вставить в группу полной текущей карты savedLogic. Это не самостоятельный запрос и не замена всей карты. Заменить UUID_SCALE на реальный UUID шкалы. Видимость или переход задаются на уровне группы отдельно.

{
  "conditionId": "c-scale-less-10",
  "widget": {"widgetId": "UUID_SCALE"},
  "option": {"id": 7},
  "answer": {"label": "10", "optionId": "10"},
  "statement": {"signature": ""}
}

Здесь 7 означает «меньше», а "10" — числовой порог в строковом виде, а не UUID варианта. Для «значение шкалы больше 5» использовать option.id: 9 и порог "5". У последнего условия группы statement.signature пустая; связка AND/OR относится к следующему условию, если оно есть.

Примеры записей для полной карты

Это фрагменты, которые нужно вставить в полную текущую карту, а не отправить вместо неё. Замените все строки UUID_* реальными id из структуры; имя скрытой переменной должно уже существовать. Примеры разных сценариев независимы.

Переход по выбранному варианту (запись внутри savedLogic):

{
  "UUID_SOURCE": [{
    "conditionGroupId":"g1","actionType":"jump","logicType":"routing",
    "jumpTo":{"widgetId":"UUID_TARGET"},
    "conditionsData":[{"conditionId":"c1","widget":{"widgetId":"UUID_SOURCE"},"option":{"id":1},"answer":{"optionId":"UUID_OPTION"},"statement":{"signature":""}}]
  }]
}

Показ одного вопроса и скрытие другого по тому же условию (запись внутри savedLogic):

{
  "UUID_SOURCE": [{
    "conditionGroupId":"g2","actionType":"show","logicType":"visibility",
    "jumpTo":{"widgetId":"UUID_SHOW"},
    "visibilityActions":[{"action":"hide","targetWidget":{"widgetId":"UUID_HIDE"}}],
    "conditionsData":[{"conditionId":"c2","widget":{"widgetId":"UUID_SOURCE"},"option":{"id":1},"answer":{"optionId":"UUID_OPTION"},"statement":{"signature":""}}]
  }]
}

Скрытая переменная utm_source равна yandex (запись внутри savedLogic; источник — вопрос-якорь группы):

{
  "UUID_SOURCE": [{
    "conditionGroupId":"g3","actionType":"jump","jumpTo":{"widgetId":"UUID_TARGET"},
    "conditionsData":[{"conditionId":"c3","widget":{"widgetId":"UUID_SOURCE"},"extraField":true,"extraFieldName":"utm_source","option":{"id":1},"answer":{"label":"yandex","optionId":"yandex"},"statement":{"signature":""}}]
  }]
}

Показ/скрытие внутри inline-группы — запись в savedInlineGroupLogic, не в savedLogic. Внешний UUID относится к группе, а UUID условия и целей — к её groupWidgets:

{
  "UUID_INLINE_GROUP": [{
    "conditionGroupId":"ig1",
    "actions":[{"action":"show","targetWidget":{"widgetId":"UUID_CHILD_SHOW"}},{"action":"hide","targetWidget":{"widgetId":"UUID_CHILD_HIDE"}}],
    "conditionsData":[{"conditionId":"ic1","widget":{"widgetId":"UUID_CHILD_SOURCE"},"option":{"id":1},"answer":{"optionId":"UUID_CHILD_OPTION"},"statement":{"signature":""}}]
  }]
}

Три правила, без которых маршрут собирается неверно.

1. Безусловный переход задаётся через defaultConditions, а не пустой группой условий.

Не заполняйте defaultConditions последовательными переходами между всеми вопросами. Чтобы респондент пошёл на следующий вопрос по порядку, оставьте исходный вопрос без записи в этой карте. Явная запись нужна, когда маршрут должен идти в другое место. Она сохраняет выбранную цель после перестановки или вставки вопросов; поэтому запись на нынешний соседний вопрос может перестать означать «следующий шаг» после изменения структуры.

Чтобы вернуть обычный следующий шаг, удалите запись исходного вопроса из прочитанной карты и сохраните полную оставшуюся карту. Не отправляйте только изменённый UUID: переданная карта заменяется целиком. Служебный defaultConditionsVersion ведёт backend; вручную передавать его инструменту не нужно.

Группа из savedLogic с пустым conditionsData не означает «переходить всегда» — наоборот, такая группа отбрасывается как всегда-истинная, и вопрос уходит к следующему по порядку. Если из вопроса всегда нужно вести в одно место, это defaultConditions:

{
  "defaultConditions": { "uuid-вопроса": {"widgetId": "uuid-цели"} }
}

Для обычного условного перехода или показа/скрытия в savedLogic нужно хотя бы одно условие в conditionsData. Дисквалификация по квоте — исключение. Пример defaultConditions выше также является фрагментом: сохраните остальные переходы этой карты.

2. Циклы запрещены.

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

Если по замыслу человек должен что-то выбрать заново — заведите отдельный вопрос ниже по потоку вместо возврата к пройденному.

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

3. Дисквалификация по квоте — это группа без условий.

Квота — это группа с actionType = screenout, режимом answer_quota и пустым conditionsData. Условие в такой группе делает её обычной дисквалификацией по ответу: правило сработает, но квота считаться не будет. Инструмент на такую пару вернёт предупреждение.

Порог и источник квоты задаются внутри screenoutConfig, а не условиями:

{
  "conditionGroupId": "g1",
  "actionType": "screenout",
  "jumpTo": {"widgetId": "uuid-экрана-отсева"},
  "conditionsData": [],
  "screenoutConfig": {
    "mode": "answer_quota",
    "sourceWidgetId": "uuid-вопроса",
    "quotaType": "answer_option",
    "quotaLimit": "100",
    "quotaOptionId": "uuid-варианта"
  }
}

update_quiz_note

Добавляет или изменяет внутреннюю заметку опроса. Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Заметка опроса обновлена."
    },
    {
      "type": "text",
      "text": "{\"quiz_id\":1,\"notes\":\"Текст внутренней заметки\"}"
    }
  ],
  "isError": false,
  "quiz_id": 1,
  "notes": "Текст внутренней заметки"
}

upload_quiz_media

Загрузка медиа (изображение, видео, аудио) для блока multimedia. (Требуется платный тариф). Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Медиа загружено. url: https://storage.webask.io/... — подставьте в multimedia.imgUrl."
    },
    {
      "type": "text",
      "text": "{\"url\":\"https://storage.webask.io/...\"}"
    }
  ],
  "isError": false,
  "url": "https://storage.webask.io/..."
}

Отказ. Текст отказа называет причину: недопустимый формат (список форматов в сообщении), файл больше лимита тарифа на один файл, место кончилось или этот файл в свободное место не помещается (кроме пространства с рабочим своим хранилищем — там место не считается), недоступно на тарифе, не скачалось по url, некорректный base64. Если файл не сохранился по внутренней причине, в текст попадает её короткое описание (до 200 знаков) и пометка, что файл не сохранён — повтор того же запроса даст тот же результат, текст причины нужно передать в поддержку. Полная запись со стектрейсом — в канале mcp и media.

upload_quiz_widget_image

Загрузка картинки для виджета "Выбор из списка" с медиа-вариантами. Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Изображение загружено. url: https://storage.webask.io/... — подставьте в choiceImageEntities[].link."
    },
    {
      "type": "text",
      "text": "{\"url\":\"https://storage.webask.io/...\"}"
    }
  ],
  "isError": false,
  "url": "https://storage.webask.io/..."
}

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

Библиотека избранных вопросов

Вопросы, которые автор переиспользует в разных опросах. В библиотеке лежит снимок вопроса, а не ссылка: правка исходного опроса библиотеку не меняет, и наоборот. До 100 вопросов на workspace; JSON-кодирование data ограничено 65 536 байтами. Проверяется доступ к workspace.

get_favorite_questions

Возвращает workspace_id, items со снимками вопросов и limit: 100.

save_favorite_question

При обновлении обязательные name, widget_type и data нужны снова. Это перезапись снимка: пропущенные необязательные поля сбрасываются к указанным значениям, а не сохраняются из прежней записи. В ответе — workspace_id и question.

Пример аргументов обновления метаданных вместе со снимком (объект data и id нужно взять из своих ресурсов; пример не заменяет полный снимок):

{
  "workspace_id":5,
  "favorite_question_id":12,
  "name":"Предпочтительный канал связи",
  "widget_type":"choice",
  "data":{"id":"UUID_SOURCE","type":"choice"},
  "choice_type":null,
  "choice_multiple":false,
  "source_quiz_id":123,
  "source_widget_id":"UUID_SOURCE"
}

delete_favorite_question

В ответе — workspace_id и favorite_question_id. Вставленные в опросы копии вопроса сохраняются.

Запись на встречи

Респондент отвечает на вопросы и в конце выбирает свободное время. Расписание живёт на уровне аккаунта и подключается к опросам отдельно — одно расписание может обслуживать несколько опросов.

Полные параметры, условная обязательность полей и права восьми инструментов описаны в инструментах аккаунта.

Два способа задать время. weekly — повторяющиеся часы по дням недели, самый частый случай. slots — список конкретных дат и интервалов для разовых встреч. Режим выбирается полем schedule_mode.

Часовые пояса. Часы в weekly, manual_slots и overrides задаются в поясе расписания — респонденту слоты пересчитываются при показе. А границы записей и блокировок задаются в UTC: пояс расписания и пояс респондента различаются, и UTC — единственный способ не промахнуться.

Права. Чтение расписаний и журнала требует права на просмотр результатов — в журнале персональные данные респондентов. Любые правки — права на настройки опроса.

«Только свои». У расписания есть автор — кто его создал или скопировал; расписания, созданные до 12.10.2026, считаются расписаниями владельца. При праве на настройки «только свои» участник меняет, копирует, удаляет и закрывает время только в своих расписаниях — get_schedulers отдаёт у каждого can_edit. При праве на результаты «только свои» get_booking_journal показывает записи только по видимым участнику опросам, а update_booking меняет только их. Отказ — обычная ошибка инструмента с объяснением права.

Выключить приём записей можно, не удаляя расписание: save_scheduler с is_active: false. Удаление необратимо и уносит записи.

Переменные опроса и скрытые опции

Все операции записи в этом разделе требуют доступа к опросу и права edit_quiz. Имена переменных и ключи/значения скрытых опций — строки до 250 символов. UUID существующих объектов берите из ресурсов опроса; field_id — аргумент обновления/удаления, а в полученном объекте переменной UUID называется id.

Переменные опроса

create_quiz_variable

Создаёт новую скрытую переменную (extra field) опроса. Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Скрытая переменная создана."
    },
    {
      "type": "text",
      "text": "{\"item\":{\"id\":\"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\"name\":\"Имя переменной\"}}"
    }
  ],
  "isError": false,
  "item": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Имя переменной"
  }
}

Аргументы создания:

{"quiz_id":123,"name":"utm_source"}

Повторное создание с тем же именем или id вернёт ошибку, а не обновит переменную.

update_quiz_variable

Обновляет имя скрытой переменной. Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Скрытая переменная обновлена."
    },
    {
      "type": "text",
      "text": "{\"item\":{\"id\":\"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\"name\":\"Новое имя переменной\"}}"
    }
  ],
  "isError": false,
  "item": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Новое имя переменной"
  }
}

delete_quiz_variable

Удаляет скрытую переменную. Структура ответа (успех):

{
  "content": [{"type": "text", "text": "Скрытая переменная удалена."}],
  "isError": false
}

Скрытые опции

create_hidden_option

Создаёт скрытую служебную опцию всего опроса. Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Скрытая опция создана."
    },
    {
      "type": "text",
      "text": "{\"item\":{\"id\":10,\"name\":\"redirect_url\",\"value\":\"https://example.com/thanks\"}}"
    }
  ],
  "isError": false,
  "item": {
    "id": 10,
    "name": "redirect_url",
    "value": "https://example.com/thanks"
  }
}

update_hidden_option

Обновляет скрытую служебную опцию опроса. Структура ответа (успех):

{
  "content": [{"type": "text", "text": "Скрытая опция обновлена."}],
  "isError": false
}

delete_hidden_option

Удаляет скрытую опцию опроса. Структура ответа (успех):

{
  "content": [{"type": "text", "text": "Скрытая опция удалена."}],
  "isError": false
}

create_widget_hidden_option

Создаёт скрытую служебную опцию конкретного виджета. Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Скрытая опция виджета создана."
    },
    {
      "type": "text",
      "text": "{\"item\":{\"id\":11,\"widget_uuid\":\"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\"name\":\"custom_key\",\"value\":\"custom_value\"}}"
    }
  ],
  "isError": false,
  "item": {
    "id": 11,
    "widget_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "custom_key",
    "value": "custom_value"
  }
}

update_widget_hidden_option

Обновляет опцию конкретного виджета. Структура ответа (успех):

{
  "content": [{"type": "text", "text": "Скрытая опция виджета обновлена."}],
  "isError": false
}

delete_widget_hidden_option

Удаляет опцию конкретного виджета. Структура ответа (успех):

{
  "content": [{"type": "text", "text": "Скрытая опция виджета удалена."}],
  "isError": false
}

Папки и доступ к ним

create_folder

Создаёт новую папку для группировки опросов. Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Папка успешно создана."
    },
    {
      "type": "text",
      "text": "{\"message\":\"OK\"}"
    }
  ],
  "isError": false,
  "message": "OK"
}

manage_workspace_folder

Наводит порядок в папках: переименование, удаление, перестановка.

Удаление папки уносит и все опросы внутри неё вместе с ответами респондентов, поэтому непустая папка удаляется только с confirm_delete_quizzes. Папка по умолчанию не удаляется. Одноимённых папок в аккаунте не заводится.

Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Папка удалена."
    },
    {
      "type": "text",
      "text": "{\"message\":\"OK\",\"data\":{\"workspace_id\":1,\"folder_id\":12,\"deleted_quizzes\":3}}"
    }
  ],
  "isError": false,
  "message": "OK",
  "data": {
    "workspace_id": 1,
    "folder_id": 12,
    "deleted_quizzes": 3
  }
}

manage_folder_access

Доступ к папке со стороны самой папки: members, add, remove.

Доступ участника к опросам держится на привязке к папкам. Соседний set_workspace_member_folders смотрит с другой стороны — перезаписывает весь список папок одного участника целиком, поэтому для точечной выдачи и снятия годится этот инструмент.

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

Темы оформления

Темы оформления

apply_quiz_theme

Применяет указанную тему оформления к опросу. Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Тема #3 применена к опросу #1."
    },
    {
      "type": "text",
      "text": "{\"quiz\":{\"id\":1,\"name\":\"Мой опрос\",\"url_shared\":\"https://...\",\"answer_count\":0,\"quiz_data\":{\"ids\":[],\"entities\":{}},\"settings\":{\"theme_id\":3,\"...\":\"...\"},\"info\":{}}}"
    }
  ],
  "isError": false,
  "quiz": {
    "id": 1,
    "name": "Мой опрос",
    "url_shared": "https://...",
    "answer_count": 0,
    "quiz_data": {
      "ids": [],
      "entities": {}
    },
    "settings": {
      "theme_id": 3,
      "...": "..."
    },
    "info": {}
  }
}

create_theme

Создаёт новую тему в workspace и применяет к опросу. (Требуется платный тариф). Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Тема создана и применена к опросу."
    },
    {
      "type": "text",
      "text": "{\"theme_id\":5,\"name\":\"Тема 1\"}"
    }
  ],
  "isError": false,
  "theme_id": 5,
  "name": "Тема 1"
}

Недопустимое значение опций «Дизайна» — ошибка инструмента (isError: true); кабинет в таком случае молча сохраняет «нет значения». Адреса — без пробелов, кавычек, скобок, <> и \. custom_font_file_id, bg_video_file_id, bg_mobile_image_file_id инструменты не принимают: id появляются только при загрузке файла в кабинете, загрузки файлов темы через ассистента нет — передаётся адрес. background_type_id: 3 — видео на фоне.

update_theme

Обновляет существующую тему (настройки аналогичны create_theme). Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Тема успешно обновлена."
    },
    {
      "type": "text",
      "text": "{\"theme\":{\"id\":5,\"workspace_id\":1,\"name\":\"Тема 1\",\"base_font_id\":1,\"background_type_id\":2,\"bg_gradient_start\":\"#00d4ff\",\"bg_gradient_end\":\"#090979\",\"buttons_type_id\":1,\"created_at\":\"...\",\"updated_at\":\"...\"}}"
    }
  ],
  "isError": false,
  "theme": {
    "id": 5,
    "workspace_id": 1,
    "name": "Тема 1",
    "base_font_id": 1,
    "background_type_id": 2,
    "bg_gradient_start": "#00d4ff",
    "bg_gradient_end": "#090979",
    "buttons_type_id": 1,
    "created_at": "...",
    "updated_at": "..."
  }
}

manage_theme

Копия, удаление и возврат темы оформления: copy, delete, restore.

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

Цвет текста ответов и выпадающего списка

update_theme дополнительно принимает answers_text_color и dropdown_bg_color (оба string): цвет текста ответов и цвет фона выпадающего списка. Формат обоих — #RRGGBB (шесть шестнадцатеричных цифр). Это параметры верхнего уровня рядом с workspace_id и theme_id, а не вложенный объект. Пример аргументов:

{"workspace_id":7,"theme_id":14,"answers_text_color":"#20202A","dropdown_bg_color":"#FFFFFF"}

Необходимо передать хотя бы одно поле оформления. Требуются право theme с учётом владельца темы и платный тариф; тема должна принадлежать указанному воркспейсу.

Раздача опроса: ссылка, QR-код, пароли, печать

set_quiz_link

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

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

Требуются право settings и тарифная возможность изменения адреса. Результат содержит quiz_id, uri и previous_uri.

manage_quiz_qr_code

QR-код опроса: show, generate, delete_logo.

Код собирается по ссылке опубликованного опроса, поэтому неопубликованный опрос получает отказ — кодировать нечего. Незаданные настройки берутся из прошлой сборки, а не из умолчаний. Повторный generate с теми же настройками отдаёт готовый файл и regenerated: false: каждая сборка пишет новый файл и списывает место с тарифа. Пересобрать принудительно — force.

Логотип в центре кода загружают в кабинете: через ассистента картинку не передать. Уже загруженный логотип код учитывает, а убрать его можно — delete_logo; из самого кода он уйдёт после повторной сборки. SVG-логотип в код, собранный здесь, не вклеивается — код собирается без логотипа; с ним его рисует конструктор QR в кабинете. Не покрыто тестом.

manage_quiz_passwords

Ведёт список паролей доступа к закрытому опросу: list, add, update, delete.

Пароли хранятся хешами — прочитать заведённый пароль нельзя ни здесь, ни в конструкторе, только заменить новым. В списке видны номер и дата; по номеру в ответах (password_number визита) автор узнаёт, кто из приглашённых отвечал. Поэтому номера не переиспользуются после удаления.

Саму проверку пароля на входе включает настройка use_password в update_quiz_settings.

manage_quiz_unique_links

Ведёт наборы уникальных ссылок на опрос — отдельных адресов https://<домен опроса>/s/<код> с лимитом ответов, сроком, расписанием и паролем: list_groups, get_group, create_group, update_group, delete_group, list_links, add_links, update_link, bulk_links, export_links.

Чтение (list_groups, get_group, list_links, export_links) — по праву view_results, остальное — по праву settings. Ошибка проверки приходит машинным кодом поля: Проверка не пройдена: max_uses: max_uses_above_group. Набор или ссылка другого опроса — «нет такого набора или ссылки».

Выпускать ссылки (create_group, add_links) и менять настройки (update_group, update_link с чем-либо кроме active) можно на тарифе «Стандарт» и выше — опция publication.unique_links; без неё тарифный отказ. Чтение, выгрузка, включение, выключение и удаление уже выпущенного работают и без опции.

Инструмент помечен как необратимый (удаляет наборы и ссылки) и выходящий наружу (выпускает адреса, которые открываются респондентам).

Во всех действиях обязательны quiz_id и action. Условия остальных полей:

В реестре именно эти десять действий. Одну ссылку удаляют через bulk_links с bulk_action: "delete" и ids: [501]. Пустой ids не означает весь набор. Без ids отбор действует на всех страницах; search по умолчанию пуст, show — all. Удаление без ids требует непустого search или show, отличного от all; целиком набор удаляет delete_group.

На опрос допускается до 50 живых наборов. create_group и add_links выпускают новые адреса при каждом успешном вызове: повтор запроса после потери ответа может создать дубликат набора или ещё одну пачку ссылок. Сначала прочитайте list_groups/list_links и проверьте результат. У этих действий нет ключа идемпотентности.

Поля changes для набора (update_group):

Поля changes для ссылки (update_link):

Например, аргументы создания и проверки изменения лимита:

{"quiz_id":42,"action":"create_group","name":"Отдел продаж","labels":["Москва","Казань"],"max_uses":1}

{"quiz_id":42,"action":"update_group","group_id":12,"changes":{"max_uses":2},"dry_run":true}

export_links отдаёт тот же файл, что «Скачать» в кабинете: все ссылки набора, колонки — адрес, код, метка, число ответов, незаконченные, время последнего ответа и доступ. Результат — download_url, одноразовая подписанная ссылка на час, как у остальных выгрузок ассистента.

Пагинация, search и show не ограничивают выгрузку: в файл идут все не удалённые ссылки набора.

Ответы по ссылкам фильтруются в get_quiz_answers и generate_filtered_report полями unique_link_group_id / unique_link_ids.

export_quiz_print

Собирает печатную версию опроса — самих вопросов, не ответов.

Форматы pdf, word, txt, html; размер шрифта влияет на вёрстку печатной страницы. Возвращает подписанную ссылку на час. PDF собирает headless-браузер, поэтому падает независимо от остальных форматов — отказ приходит с внятным текстом.

Поля sheet — все необязательны, не переданное берёт значение по умолчанию.

• Права: хватает любого из двух — settings или view_results; при значении «только свои» — только опросы, созданные участником. Нет ни того ни другого — отказ с объяснением по праву view_results.
• Значение вне списка — отказ с текстом ошибки по полю.
• Надпись сервиса снимается только на тарифе с отключаемым копирайтом, иначе copyright: false игнорируется. На таком тарифе надписи нет и тогда, когда её отключили в брендинге воркспейса.
• В txt нет логотипа, QR-кода, размера листа и номеров страниц; в html — размера листа и номеров страниц.

Требуется право settings. Например, аргументы печати PDF с полями для заполнения:

{"quiz_id":42,"format":"pdf","font":"medium","sheet":{"header":true,"fields":true,"lines":4,"paper":"a4","numbering":true}}

Ответы: видимость, теги, пометки, чистка

Ответы и аналитика

toggle_answer_visibility

Скрывает или показывает конкретный ответ респондента. Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Видимость ответа обновлена."
    },
    {
      "type": "text",
      "text": "{\"answer_id\":100,\"is_exclude\":true}"
    }
  ],
  "isError": false,
  "answer_id": 100,
  "is_exclude": true
}

tag_answer

Добавляет/синхронизирует теги для выбранного ответа. Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Теги ответа обновлены."
    },
    {
      "type": "text",
      "text": "{\"result\":{\"attached\":[5],\"detached\":[]}}"
    }
  ],
  "isError": false,
  "result": {
    "attached": [
      5
    ],
    "detached": []
  }
}

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

Теги ответов

tag_answer сопоставляет теги одного ответа по именам, поэтому перед ним стоит прочитать справочник — иначе появятся новые теги вместо существующих.

Аргументы delete_answer_tag

Значений по умолчанию нет. Удаление ограничено выбранным workspace: чужой или уже удалённый тег возвращает отказ. Результат содержит workspace_id и tag_id. Удаляются и все привязки этого тега к ответам.

{"workspace_id":1,"tag_id":5}

Пометка у ответа

set_answer_note ставит короткую пометку у отдельного прохождения — «перезвонить», «дубль», «жалоба». До 100 символов, пустое значение снимает.

Это не заметка к опросу целиком (update_quiz_note) и не тег (tag_answer): пометка живёт у самого ответа и видна в его строке.

Чистка ответов

delete_quiz_answers убирает ответы в корзину, возвращает их обратно или удаляет насовсем — типичная уборка после тестовых прохождений.

Обычное удаление обратимо: ответ уходит из списка и отчёта, но лежит в корзине. Безвозвратное необратимо, вместе с ответом убираются файлы респондента, и поэтому оно требует явного подтверждения в самом запросе — одного намерения модели мало.

Скрытые и отправленные на модерацию ответы инструмент не трогает, как и конструктор.

По умолчанию действие работает над перечисленными ответами (answer_ids, до 500 за раз). Для «очисти опрос» есть область scope: all — она идёт запросом, а не списком, и потому справляется с десятками тысяч ответов. В этом режиме answer_ids не нужен, зато можно передать excluded_answer_ids — что оставить как есть.

Область all затрагивает всю собранную работу, и списка id, по которому видно объём, в запросе нет — поэтому она требует confirm_purge даже для обычного удаления в корзину. Возврат из корзины ничего не стирает и подтверждения не требует. Скрытые и отправленные на модерацию ответы массовый режим тоже не трогает.

set_answers_order_mode

Порядок вопросов внутри карточки ответа. Тот же порядок получают публичная ссылка на ответы и выгрузка в Word, поэтому настройка меняет и то, что видят другие.

get_answer_extra_field_values

Показывает, какие значения встречались у метки ссылки в ответах опроса.

Метки цепляют к ссылке — utm_source, идентификатор ученика, номер курса — и они приходят вместе с ответом; по ним отбирают ответы в отчёте. Имена меток отдаёт quiz://{id}/hidden_options, а этот инструмент — значения выбранного имени, с поиском и постранично: у крупного опроса их бывают тысячи. Отбор по меткам доступен не на всех тарифах.

Отчёты: фильтры, AI-отчёты, оформление, ссылки

generate_filtered_report

Формирует отчёт по опросу с фильтрацией (даты, виджеты, теги). Возвращает report_uuid. Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Фильтрованный отчет сформирован."
    },
    {
      "type": "text",
      "text": "{\"data\":{\"report_uuid\":\"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\"total\":150}}"
    }
  ],
  "isError": false,
  "data": {
    "report_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "total": 150
  }
}

Новые поля, как и остальные фильтры кроме уникальных ссылок, работают только на тарифе с опцией фильтров результатов; неверное значение — ошибка проверки. Те же ключи хранит набор save_quiz_report_filters. В data есть meta.period — посчитанные дни скользящего периода ({dateFrom, dateTo}), null — периода нет. timeFrom, timeTo, scoreValue — только числа: строка — ошибка проверки, а не условие. save_quiz_report_filters их не проверяет, но при применении нечисловое значение игнорируется.

Требуется право view_results. Без дат, условий по вопросам и тегов соответствующие дополнительные ограничения не задаются. Даты, условия и теги применяются при доступной тарифной опции фильтрации результатов. unique_link_group_id без списка выбирает весь набор, с unique_link_ids — пересечение набора и ссылок. Передавать is_screenout или is_deleted этому инструменту нельзя: таких аргументов в схеме нет.

widgets задаёт отбор ответов по условиям, а не выбор столбцов отчёта. Входная схема требует массив, но не описывает вложенные элементы: обработчик передаёт их слою фильтрации. Для рабочего условия нужны поля формы, которую читает этот слой:

Строки UUID вместо объектов не соответствуют формату слоя фильтрации. Операторы и дополнительные координаты матрицы/распределения зависят от типа вопроса; форму сохранённых условий можно прочитать через get_quiz_report_filters. Не переносите пример input на другой тип вопроса.

Для статусов используются сохранённые statuses типа report (см. save_quiz_report_filters): без сохранённого выбора — completed; unfinished и screenout зависят от тарифной опции. Ни пропуск, ни true, ни false в is_complete не заменяют этот выбор. Настройка среза меняет состояние отчёта, поэтому перед её записью учитывайте, кто ещё использует этот отчёт.

Пример аргументов:

{"quiz_id":42,"dateFrom":"01.10.2026","dateTo":"08.10.2026","unique_link_group_id":12,"unique_link_ids":[501,502]}

Пример условия «свободный ответ содержит Да»; замените UUID и тип данными своего вопроса:

{"quiz_id":42,"dateFrom":"01.10.2026","dateTo":"08.10.2026","widgets":[{"id":1,"widget_uuid":"a1b2c3d4-e5f6-4789-abcd-ef1234567890","type":"input","operator":"contains","value":"Да","condition":"OR"}]}

count_quiz_answers

Считает, сколько ответов войдёт в отчёт или в список ответов с переданными фильтрами, не выбирая сами ответы. Ответы не отмечаются просмотренными. Право view_results, нужна опция фильтров результатов в тарифе (иначе — ошибка: число означало бы «все ответы»).

В data: quiz_id, section, count. У отчёта считаются и ответы без единого отвеченного вопроса.

manage_quiz_filter_presets

Именные наборы фильтров раздела («Мои фильтры»). Набор, применённый последним (save_quiz_report_filters), от них не зависит. Список видит каждый с правом view_results; менять и удалять может автор, владелец пространства или администратор.

list отдаёт items (новые первыми), create и update — item: id, section, name, filters, author ({id, name} или null), created_at, updated_at. Ошибки: пустое имя (name_required), у раздела уже 50 наборов, набора нет или он от другого опроса, не автор и не владелец/администратор.

save_quiz_report_filters

Сохраняет набор фильтров списка ответов или отчёта. Тот же набор читают экран, публичная ссылка, PDF и Word, поэтому он меняет и то, что видят другие. Текущее состояние — в quiz://{id}/report_filters.

У типа report в наборе есть ключ statuses — срез по статусам прохождения, то есть по каким ответам считается отчёт: массив из completed (завершившие), unfinished (ушедшие, не дойдя до конца) и screenout (дисквалифицированные). Ключ не передан — прежний срез остаётся: сохранение фильтров без него не сбрасывает вкладку. Пустой массив и неизвестные значения приводятся к [completed]; unfinished и screenout закрыты опцией тарифа и на закрытом тарифе отбрасываются. Срез действует не только на экране — по нему же считаются PDF, Word и отчёт по публичной ссылке. У типа answers ключа нет.

На тарифах без опции сохранённых фильтров набор не сохраняется — инструмент вернёт отказ по тарифу. Срез отчёта — исключение: он сохраняется и без опции, потому что это состояние отчёта, а не платный фильтр.

generate_ai_report

Строит AI-отчёт по ответам опроса.

Отчёт состоит из трёх независимых разделов: текстовый анализ, сравнительный и количественный. Каждый строится отдельно, поэтому текстовый можно пересобрать, не трогая остальные. Работа идёт в очереди — инструмент сообщает, какие разделы поставлены в работу, а готовый текст забирает get_ai_report.

Пока ответов меньше порога (report_ai_v2.min_answer_count), ни один раздел не запускается: приходит отказ с числами, а не пустой успех. Повторный запуск раздела, который уже строится, ничего не ломает — он попадёт в already_running_sections. Тариф ограничивает число опросов с отчётом; пересборка существующего лимит не расходует.

Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Разделы отчёта поставлены в работу. Готовый текст — в get_ai_report."
    },
    {
      "type": "text",
      "text": "{\"quiz_id\":42,\"queued_sections\":[\"text_analysis\",\"comparative\"],\"already_running_sections\":[\"quantitative\"],\"refused_sections\":{}}"
    }
  ],
  "isError": false,
  "quiz_id": 42,
  "queued_sections": [
    "text_analysis",
    "comparative"
  ],
  "already_running_sections": [
    "quantitative"
  ],
  "refused_sections": {}
}

get_ai_report

Отдаёт готовый AI-отчёт — тот самый, что автор видит в разделе результатов.

У каждого из трёх разделов свой статус: готов, строится сейчас или не построен, и почему — мало ответов либо нет подходящих вопросов. Читать отчёт следует этим инструментом: генерация тратит лимит тарифа и упирается в задержку между перезапусками.

share_ai_report

Даёт поделиться AI-отчётом: публичной ссылкой или файлом PDF.

Ссылку открывают без входа в аккаунт. Делиться можно только построенным отчётом, и опрос должен быть опубликован: страница отчёта живёт на его адресе. Ссылка требует тарифа на публикацию результатов, PDF — на выгрузку. Ссылка на скачивание PDF действительна час.

share_summary_link / share_report_link / share_answers_link

Создаёт публичные ссылки для шеринга аналитики с заказчиками (без авторизации). Структура ответа (успех):

{
  "content": [
    {
      "type": "text",
      "text": "Публичная ссылка summary создана."
    },
    {
      "type": "text",
      "text": "{\"url\":\"https://webask.io/results/...\"}"
    }
  ],
  "isError": false,
  "url": "https://webask.io/results/..."
}

Все три инструмента требуют доступ к опросу и право view_results. Ссылка открывает выбранные данные без входа в аккаунт; результат создания ссылки не подтверждает, что её уже просмотрел заказчик.

Аргументы share_summary_link

Аргументы share_report_link

Для незавершённых и отсеянных тариф ограничивает сохранённый/выбранный срез: недоступные статусы исключаются, пустой срез заменяется completed. Поэтому is_complete:true здесь не обещает только завершённые — сохранённый срез может включать несколько доступных статусов. Даты отдельными аргументами этому инструменту не передаются.

{"quiz_id":42,"is_complete":false,"is_screenout":false,"is_deleted":false}

Аргументы share_answers_link

Приоритет флагов — удалённые → отсеянные → завершённость. При is_screenout:false отсеянные исключаются из обычного среза. Ссылка получает снимок сохранённых фильтров списка ответов; отбор по уникальным ссылкам сохраняется и без платной опции фильтров. Эти фильтры и даты дополнительно сужают выбранный срез. Результат содержит url и shared_url; повтор создаёт новую ссылку.

{"quiz_id":42,"type":"full","date_from":"2026-10-01","date_to":"2026-10-08","is_complete":true,"is_screenout":false,"is_deleted":false}

Каждый вызов создаёт новую ссылку. Номер в названии новой ссылки («Сводка #3») — порядок создания среди ссылок раздела, считая выключенные; это number из get_share_links.

get_share_links

Список публичных ссылок на сводку, отчёт или ответы опроса — сначала новые, вместе с выключенными. Нужно право view_results. Только чтение.

Ответ — total (сколько всего ссылок у раздела, с выключенными) и items: uuid, number (порядок создания с 1, выключенные считаются), url, created_at (ISO 8601 в часовом поясе пользователя), is_active, а у answers — answers_count (сколько ответов в ссылке, null — все ответы). В answers входят только ссылки на все и на выбранные ответы: ссылки респондентов на свой ответ и ссылки «все, кроме выбранных» не входят.

set_share_link_active

Выключает или включает публичную ссылку. Выключенная перестаёт открываться — публичная страница отвечает как на ссылку, которой нет; строка остаётся, ссылку можно включить обратно. Нужно право view_results. Пометки: выключение обрывает доступ (destructiveHint), включение снова открывает ссылку наружу (openWorldHint).

Успех — link: ссылка в том же виде, что в get_share_links. Повторный вызов с тем же значением ничего не меняет. Нет ссылки с таким uuid у раздела опроса — ошибка «У этого раздела опроса нет ссылки с таким uuid».

Оформление отчётов

Цвета и подписи графиков в отчёте настраиваются на двух уровнях.

• Общая палитра аккаунта — одна на весь воркспейс. Её используют опросы, у которых включён флаг results_appearance_use_shared.
• Своя палитра опроса — поле results_appearance в update_quiz_settings.

Приоритет у общей: пока флаг включён, свои цвета опроса хранятся, но не применяются, и возвращаются, когда флаг выключают. Поэтому передача results_appearance заодно выключает флаг — иначе правка не дала бы эффекта.

Объект оформления одинаков везде:

Настройки строк отчёта задаются отдельным полем report_row_options: sort_mode (default, asc, desc) и value_format (both, count, percent). null в любом из этих полей возвращает стандартный вид.

Действующее оформление опроса приходит в quiz://{id}/structure: results_appearance (своё), results_appearance_use_shared (флаг), report_row_options и effective_results_appearance — то, которое реально применится.

get_workspace_report_appearance

Общая палитра аккаунта, библиотека наборов, значения по умолчанию и списки допустимых значений.

update_workspace_report_palette

Задаёт общую палитру аккаунта. Все опросы с включённым флагом начинают рисовать отчёты ею сразу.

create_report_appearance_preset

Сохраняет набор оформления в библиотеку аккаунта, чтобы применять его к другим опросам. Набор — шаблон: его удаление или правка не меняют опросы, к которым его применяли. В воркспейсе можно хранить до 20 наборов.

delete_report_appearance_preset

Удаляет набор из библиотеки. Опросы, к которым его применяли, своё оформление сохраняют.

Выгрузки ответов и отчётов

export_answers_csv / export_answers_xlsx / export_answers_word / export_answers_spss

Выгружают выбранный срез ответов: CSV, Excel, Word или SPSS (.sav). Требуются доступ к опросу, право view_results и тарифная возможность выгрузки. Фильтры не совпадают по умолчанию с get_quiz_answers: здесь пропущенный is_complete означает завершённые.

Каждый из четырёх инструментов принимает следующую схему; обязательным является только quiz_id.

Приоритет флагов: удалённые → отсеянные → завершённость. При is_screenout:false отсеянные исключаются из обычного среза. Фильтры ID дополнительно сужают этот срез, не заменяют его. При одновременном включении и исключении применяется пересечение: включённый и исключённый ID в файл не попадает.

В проверенной реализации из массивов ids и excludedIds учитывается только первый элемент. Для надёжного отдельного среза передавайте один ID; несколько ID в массиве не гарантируют нужную выборку. ids также требует тарифной опции фильтрации результатов, без неё включение ID не применяется; excludedIds применяется независимо. Перед отправкой файла заказчику проверьте фактический состав выгрузки. Аргументов unique_link_group_id / unique_link_ids у этих четырёх инструментов нет.

Пример аргументов выгрузки с исключением одного тестового ответа:

{"quiz_id":42,"is_complete":true,"is_screenout":false,"is_deleted":false,"excludedIds":[100]}

Полный результат CSV с данными (URL и текст сообщения иллюстративны):

{
  "content": [
    {"type":"text","text":"Файл CSV готов. Скачать по ссылке (действует 1 час, после скачивания файл удаляется): https://mcp.webask.io/export/example"},
    {"type":"text","text":"{\"quiz_id\":42,\"format\":\"csv\",\"download_url\":\"https://mcp.webask.io/export/example\"}"}
  ],
  "isError": false,
  "quiz_id": 42,
  "format": "csv",
  "download_url": "https://mcp.webask.io/export/example"
}

Данные остаются соседними полями и дублируются JSON-текстом в следующем блоке content; отдельный вложенный result добавлять не нужно. Это результат инструмента внутри JSON-RPC result. Отказ инструмента отмечается isError:true; дополнительные детали, если они есть, также попадают в JSON-блок content.

Ссылка подписана на один час; после скачивания файл удаляется. Забытые файлы убирает почасовая уборка. У Word поле format результата равно doc, у SPSS — spss. Если ответов для выгрузки нет, CSV/XLSX/Word возвращают пустую строку download_url, SPSS — null; отсутствие ссылки не надо заменять выдуманным URL. SPSS включает параметры ссылки вместе с ответами.

export_summary_pdf

Выгружает сводную аналитику в PDF. Обязателен только quiz_id: integer; дополнительных фильтров в схеме нет. Пример аргументов:

{"quiz_id":42}

export_filtered_report_pdf / export_filtered_report_word

Выгружают отчёт с сохранённым состоянием и фильтрами в PDF/Word. Обязателен только quiz_id: integer; даты, ID ответов, флаги завершённости и report_uuid этим инструментам не передаются. Сначала прочитайте сохранённые фильтры через get_quiz_report_filters и проверьте срез отчёта. Изменение сохранённых фильтров меняет состояние отчёта и для других пользователей.

{"quiz_id":42}

Для всех трёх выгрузок отчётов требуется право view_results и доступная тарифная выгрузка. Результат содержит quiz_id, format (pdf или doc) и download_url с той же оболочкой и сроком ссылки, что выше.

Интеграции: CRM, мессенджеры, таблицы, вебхуки

Интеграции опроса

get_quiz_integrations показывает, куда опрос отправляет ответы кроме почты — Telegram, MAX, AmoCRM, Битрикс24, Zapier, Google Таблицы.

По каждой видно три вещи: подключена ли она, включена ли отправка и разрешает ли её тариф. Поле blocked называет причину, по которой ответы не уходят: not_connected, disabled или blocked_by_tariff; пусто — значит отправка работает.

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

manage_quiz_crm

Отправка ответов в CRM: show, activate, deactivate, check для amocrm или bitrix24.

Переключатель отправки и проверка живости подключения. Токен CRM отзывают на её стороне, и со стороны опроса это выглядит как молчащая интеграция — check отвечает отказом, когда доступа нет, а не «связь в порядке». Без подключённого портала любое действие отказывает: подключение требует входа в аккаунт CRM и делается в кабинете. Сопоставление полей здесь не настраивается — см. get_quiz_crm_fields.

get_quiz_crm_fields

Справочники CRM и текущее сопоставление полей. Только чтение.

Отдаёт то же, что человек видит в форме настройки: поля лида, сделки, контакта и компании, воронки со стадиями, ответственных, типы — и рядом сохранённое у опроса сопоставление. Справочники читаются живыми запросами в портал, поэтому вызов не мгновенный и вернёт отказ при отозванном доступе. По умолчанию берутся только lead и contact: каждый раздел — отдельный запрос в CRM.

Менять сопоставление нельзя намеренно: настройки хранятся свободным JSON, форму которого задаёт адаптер доставки, и блок не той формы молча ломает отправку заявок. В ответе стоит mapping_editable: false.

manage_quiz_crm_mapping

Сопоставление полей опроса с полями Bitrix24. Одна сущность за вызов: lead, contact, company, deal.

Сущность заменяется целиком, остальные вызов не трогает; набор полей тоже заменяется целиком, иначе убранное поле осталось бы в настройках. Правка полей не выключает отправку: незаданный enabled берётся из прежних настроек.

Форма настроек — свободный JSON, и её задаёт адаптер доставки, а не валидация запроса (кабинет проверяет из всего блока два поля). Поэтому блок неверной формы не отклоняется, а молча ломает отправку заявок.

Форма блока сущности:

<entity> = {
    enabled: bool,            // сущность участвует в отправке
    fields: {                 // ключ — имя поля Bitrix24 (TITLE, PHONE, UF_CRM_…)
        <field>: {
            widget_id?: string,     // UUID вопроса: значение берётся из ответа
            static_value?: string   // либо постоянное значение
        }
    },
    category_id?: string,     // воронка, только у deal
    stage_id?: string         // стадия этой воронки, только у deal
}

В поле берётся widget_id, а при его отсутствии static_value. Название сущности обязательно: если TITLE собрать не удалось, адаптер подставляет Lead #<id ответа> или Deal #<id ответа>. У воронки по умолчанию стадия не начинается с C, у воронки N — начинается с CN:.

Инструмент отклоняет до записи: поле, где заданы и вопрос, и постоянное значение (адаптер взял бы вопрос, значение потерялось бы); поле без источника; стадию из чужой воронки; стадию у сущности, кроме сделки. Если стадия всё же отвалилась при сохранении, в ответе stage_dropped.

manage_quiz_amocrm_mapping

Сопоставление полей опроса с полями amoCRM. Отдельный инструмент, потому что форма другая: не «сущность → поля», а «что активно» плюс словари по номерам.

Блоки: deal — сделки в перечисленных воронках, list — контакт (0), компания (1) и каталоги, task — задачи. Один блок за вызов, блок заменяется целиком, соседние не трогаются, незаданные словари остаются прежними — правка стадии не стирает сопоставление полей. Пустой active сохраняется как осмысленное значение «не создавать».

Каждое значение проверяется по живым справочникам портала до записи: воронка существует, стадия принадлежит своей воронке, идентификатор поля есть в справочнике, ответственный есть в списке пользователей. В bind значение обязано быть идентификатором вопроса — постоянных значений эта форма не поддерживает, и текст молча дал бы пустое поле в CRM. Если портал справочники не отдал, инструмент отказывает, а не пишет «на удачу».

manage_quiz_messenger

Настройки отправки ответов в мессенджер: telegram или max.

Отвечает на вопрос «куда именно уходят заявки»: список чатов, групп и людей, тема сообщения, какие вопросы из него исключены, есть ли кнопки. Действия: show, activate, deactivate, delete, toggle_buttons, save_widgets, remove_recipient, test.

Токены здесь не вводят: бот платформенный. activate заводит подключение и отдаёт bot_url — по этой ссылке человек добавляет бота в чат, и до этого шага отправлять некуда. Любое действие кроме activate отвечает отказом, если интеграция не подключена. test отказывает при выключенной отправке и при пустом списке получателей. Выбор темы форума в группе Telegram в инструмент не входит — текущая тема каждого получателя видна в show. Журнал доставки — get_integration_logs.

get_quiz_messenger_link

Ссылка, по которой человек добавляет бота Telegram или MAX в чат, — только чтение.

В отличие от manage_quiz_messenger с activate, не заводит интеграцию и не включает отправку — записывает только временный код ссылки. Интеграция уже есть — отдаётся её ссылка. Нет — ссылка с временным кодом (живёт 7 дней, повторный вызов отдаёт тот же код и продлевает срок); запись интеграции появляется, только когда человек открывает ссылку и нажимает «Старт» в боте. Если к этому моменту интеграцию уже завели в кабинете, бот подключается к ней — её ссылка в кабинете не меняется.

Ответ: connected (интеграция включена: бот добавлен «Стартом» или отправку включили в кабинете), bot_url, для Telegram ещё group_url (добавить бота в группу). Гейт как у manage_quiz_messenger: тариф на интеграцию и право integrations.

Например, аргументы запроса ссылки:

{"quiz_id":42,"messenger":"telegram"}

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

get_integration_logs

Журнал отправки ответов в мессенджер: telegram или max.

Отдаёт текст отказа (бота выгнали из группы, чат удалён, токен отозван) и unsent_count. Журнал вебхуков — отдельный get_quiz_webhook_logs. Неподключённая интеграция отвечает отказом, а не пустым журналом.

total и last_page — с учётом status. counts (all, failed, queued) — по всему журналу, от status и страницы не зависит; counts.failed = unsent_count.

resend_integration_logs

Дослать в мессенджер то, что не ушло: одну запись по log_id или все неудачные за период.

Отправка идёт очередью, поэтому в ответе queued — сколько поставлено, а не сколько дошло. Повтор пачкой берёт ограниченное число записей за раз; если срезано, приходит truncated: true и вызов нужно повторить.

manage_quiz_google_sheets

Выгрузка ответов в Google Таблицы: show, activate, deactivate, delete, save_widgets, save_switchers, set_sync_mode, sync_now, export_all.

show отвечает на «почему в таблице нет новых ответов»: адрес и название таблицы, живой ли доступ (его отзывают на стороне Google), режим обновления, когда выгружали последний раз, какие вопросы исключены.

Состав вопросов задаётся целиком, поэтому вызов save_widgets без hidden_widget_ids отклоняется: иначе он снял бы все исключения и в таблицу поехали бы вопросы, которые автор оттуда убрал. Переключатели меняются по одному, но хотя бы один нужен. Подключение аккаунта и выбор таблицы — в кабинете: там вход в аккаунт Google и окно Google Диска.