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

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

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

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

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

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

В примерах ниже приведён полный успешный ответ (включая content и isError и все возвращаемые данные).

Пример ответа с ошибкой:

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

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

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

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

• имя права и его код — Недостаточно прав: для этого действия нужно право «Удаление опросов» (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.

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

Правка виджетов, логики и текстов опроса отдельного права не требует — как и в конструкторе.

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

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

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

create_quiz

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

{
  "content": [{"type": "text", "text": "Опрос успешно создан (ID: 1)."}],
  "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 переименован в \"Новое название опроса\"."}],
  "isError": false,
  "quiz_id": 1,
  "name": "Новое название опроса"
}

duplicate_quiz

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

{
  "content": [{"type": "text", "text": "Опрос #1 успешно дублирован (новый ID: 2)."}],
  "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": "Опрос архивирован."}],
  "isError": false,
  "quiz_id": 1,
  "archive_at": "2024-01-15 12:00:00",
  "is_archived": true
}

delete_quiz

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

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

restore_quiz

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

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

publish_quiz

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

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

{
  "content": [{"type": "text", "text": "Опрос #1 успешно опубликован."}],
  "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."}],
  "isError": false,
  "quiz_id": 1,
  "folder_id": 5
}

make_quiz_template

Создаёт шаблон на основе текущего опроса. Структура ответа (успех):

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

get_quiz_versions

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

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

restore_quiz_version

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

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

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

{
  "content": [{"type": "text", "text": "Версия восстановлена в черновик. Чтобы её увидели респонденты, опубликуйте опрос."}],
  "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 произвольный чужой опрос нельзя: берутся только те, что лежат в каталоге.

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

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

Заморозка опроса кампанией. Пока по опросу идёт оплаченная кампания за респондентов, его состав менять нельзя: респонденты проходят то, что оплачено и промодерировано. 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": "Структура виджетов опроса успешно обновлена."}],
  "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": {}
  }
}

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

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

Структуру, полученную чтением, можно возвращать записью как есть: ничего вычищать из неё не нужно.

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

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

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

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

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

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

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

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

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

update_quiz_texts

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

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

update_quiz_settings

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

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

update_quiz_logic

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

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

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

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

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

{
  "defaultConditions": { "uuid-вопроса": {"widgetId": "uuid-цели"} },
  "savedLogic": { "uuid-вопроса": [ {"conditionGroupId": "g1", "jumpTo": {"widgetId": "uuid-цели"}, "conditionsData": [ ... ]} ] }
}

В savedLogic держите только переходы по условию: у каждой группы должно быть хотя бы одно условие в conditionsData.

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": "Заметка опроса обновлена."}],
  "isError": false,
  "quiz_id": 1,
  "notes": "Текст внутренней заметки"
}

upload_quiz_media

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

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

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

Вопросы, которые автор переиспользует в разных опросах. В библиотеке лежит снимок вопроса, а не ссылка: правка исходного опроса библиотеку не меняет, и наоборот. До 100 вопросов на аккаунт, снимок до 64 КБ.

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

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

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

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

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

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

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

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

create_quiz_variable

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

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

update_quiz_variable

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

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

delete_quiz_variable

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

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

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

create_hidden_option

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

{
  "content": [{"type": "text", "text": "Скрытая опция создана."}],
  "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": "Скрытая опция виджета создана."}],
  "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": "Папка успешно создана."}],
  "isError": false,
  "message": "OK"
}

manage_workspace_folder

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

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

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

{
  "content": [{"type": "text", "text": "Папка удалена."}],
  "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."}],
  "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": "Тема создана и применена к опросу."}],
  "isError": false,
  "theme_id": 5,
  "name": "Тема 1"
}

update_theme

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

{
  "content": [{"type": "text", "text": "Тема успешно обновлена."}],
  "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 говорит, скольких это коснулось. Общие темы сервиса аккаунту не принадлежат: их нельзя ни удалить, ни восстановить.

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

Адрес ссылки на опрос

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

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

manage_quiz_qr_code

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

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

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

manage_quiz_passwords

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

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

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

export_quiz_print

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

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

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

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

toggle_answer_visibility

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

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

tag_answer

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

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

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

Теги ответов

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

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

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": "Фильтрованный отчет сформирован."}],
  "isError": false,
  "data": {
    "report_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "total": 150
  }
}

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."}],
  "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 создана."}],
  "isError": false,
  "url": "https://webask.io/results/..."
}

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

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

• Общая палитра аккаунта — одна на весь воркспейс. Её используют опросы, у которых включён флаг 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_summary_pdf, export_filtered_report_pdf, export_filtered_report_word.

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

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

export_answers_spss

Выгружает ответы в формат SPSS (.sav) — тот же набор данных, что в CSV и XLSX.

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

Параметры те же, что у export_answers_csv и export_answers_xlsx. Если подходящих ответов нет, download_url приходит null — файла не создаётся.

Интеграции: 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_integration_logs

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

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

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 Диска.

Вебхуки опроса

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

Адрес должен быть публичным http или https — внутренние адреса не принимаются.

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

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

После серии неудачных отправок вебхук отключается сам. Это видно в списке, включить обратно можно тем же toggle_quiz_webhook.

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

Zapier

manage_quiz_zapier — со стороны опроса это один переключатель: show, activate, deactivate, delete.

Связки собираются на стороне Zapier по подписке, ключей здесь вводить не нужно. delete снимает и подписки: связка перестанет получать ответы, и собирать её придётся заново в Zapier. show заодно показывает, сколько связок слушает опрос.

Счётчики и пиксели

manage_quiz_analytics ведёт Google Аналитику, Яндекс.Метрику и пиксели VK и Facebook: show, save, activate, deactivate, delete. Сервис выбирается параметром service — google, yandex, vk, fb.

Номер счётчика не секрет, он виден в коде любой страницы, поэтому здесь ничего чужого вводить не приходится. Значение пишется в двух местах — в строку интеграции и в версию опроса, откуда его читает рендер; иначе счётчик числился бы включённым, а на странице не появлялся. У Google есть version (ga4 или ua), у Яндекса — is_webvisor.

Почта опроса

Письма, которые опрос шлёт сам по себе: уведомление автору о новом ответе и копия ответа респонденту. К e-mail рассылкам по контактным спискам это отношения не имеет — они в tools-mailing.md.

Письма опроса

Две независимые рассылки: уведомление автору о новом ответе и копия ответа респонденту. У каждой свой переключатель и свой шаблон.

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

Три вида шаблона. Стандартное письмо WebAsk (use_default_tmpl), свой визуальный шаблон (formatted_letter — HTML из редактора) и полностью свой HTML (raw_html + raw_enabled), который уходит как есть, без обёртки WebAsk.

Полностью свой HTML работает только с подключённым своим SMTP. Без него письмо всё равно уйдёт визуальным шаблоном — сохранение при этом успешно, поэтому инструмент возвращает предупреждение. Подключён ли свой SMTP, видно в get_quiz_email_settings (own_smtp_connected).

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

Адрес автора работает только после подтверждения. При добавлении на него уходит письмо со ссылкой; пока человек не подтвердил, уведомления туда не идут. В списке это поле checked.

Адрес респондента не задаётся напрямую. Он берётся из ответа на вопрос с почтой или из скрытой переменной опроса — на источник указывает client_source. Если переменную переименовать, указатель переезжает сам.

Копия ответа респонденту доступна не на всех тарифах, число адресов автора тоже ограничено тарифом.

manage_workspace_smtp

Своя почтовая служба аккаунта: show, logs, enable, disable, test.

Подключение одно на аккаунт: им уходят и письма опроса, и e-mail рассылки.

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

confirm_quiz_email_recipient

Подтверждает адрес получателя копий ответов кодом из письма.

Без подтверждения адрес не получает ничего: add_quiz_email_recipient только заводит его, и в базе он лежит с checked = false. Код приходит на сам адрес — ассистент его не видит, диктует человек. Попыток ограниченное число, поэтому есть resend_code.

E-mail рассылки

Кампании по контактным спискам аккаунта: письма уходят людям, которых автор завёл сам, а не участникам прохождения опроса. Письма, которые шлёт сам опрос (уведомление автору о новом ответе, копия ответа респонденту), — в tools-quiz-emails.md.

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

get_mailing_state

Состояние e-mail рассылок аккаунта. Только чтение.

Разделы: campaigns — список со сводкой, campaign — одна кампания с показателями, recipients — получатели с фильтром по статусу доставки, contact_lists — списки и сводка по контактам, contacts — контакты одного списка, templates — шаблоны писем, reputation — доля отказов и жалоб (по ней почтовые службы решают, пускать ли письма дальше), balance — сколько писем осталось, settings — отправитель и своя почтовая служба, smtp_logs — журнал отправок.

Фильтры раздела recipients

Два независимых фильтра, оба необязательные.

statuses — что случилось с письмом: sent (отправлено), delivered (доставлено), opened (открыл), clicked (перешёл по ссылке), bounced (не доставлено), unsubscribed (отписался), complaint (пожаловался на спам). Статус у получателя один — последнее случившееся событие, поэтому открывший письмо в delivered не попадает, а перешедший по ссылке — в opened. Чтобы получить «письмо дошло» целиком, перечисляют все подходящие значения.

quiz_statuses — что получатель сделал с опросом: none (не начинал), started (начал и не закончил), completed (прошёл до конца). По этому фильтру в кабинете отбирают тех, кому досылать письмо. Прохождение считается по скрытой переменной с id получателя в ссылке письма, поэтому у кампании без привязки к опросу оно неизвестно ни у кого — фильтр вернёт пустой список, а в самих записях quizStatus будет null.

Неизвестное значение в любом из фильтров — ошибка валидации, а не молчаливое игнорирование: иначе ответ выглядел бы отфильтрованным, не будучи им.

Отправитель и своя почтовая служба аккаунта — общие с письмами опроса, настраиваются инструментом manage_workspace_smtp (см. tools-quiz-emails.md).

Аккаунт: профиль, участники, брендинг, домен, файлы

update_user_profile

Правка своего профиля: имя, язык интерфейса, часовой пояс, оформление, подписки на письма.

Часовой пояс важен отдельно — от него зависят все даты в отчётах и выгрузках. Передаются только те поля, которые нужно поменять; подписки можно менять по одной, остальные останутся как были. Смена почты и пароля недоступна (код из письма и текущий пароль), аватар тоже — это загрузка картинки. Чтение профиля — user://me.

manage_user_sessions

Активные входы в аккаунт: list, close, close_all.

Показывает устройство, браузер, город и когда заходили последний раз. Отличие от кабинета: там «закрыть все» означает «все, кроме текущей», потому что запрос идёт из браузерной сессии. Ассистент работает по ключу и своей сессии не имеет, поэтому close_all закрывает все входы, включая тот, в котором человек сейчас работает в кабинете, — и требует confirm_close_all. Закрыть чужой вход нельзя: идентификатор сверяется со своим списком. На установке без Redis инструмент отказывает — там этих данных нет.

Сведения об аккаунте и права

get_workspace_details отвечает на «что это за аккаунт и что мне в нём можно»: название, владелец ли текущий пользователь, включены ли AI-отчёты и вход через SSO, сколько папок, опросов и участников, и полный список его прав.

Половина отказов инструментов — это отсутствующее право, и по списку rights видно заранее, что получится. Рядом permissions — то же с оговоркой «только свои объекты». Возможности тарифа отдельно, в get_workspace_tariff.

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

Участники и роли

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

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

О чём стоит помнить, поручая это ассистенту:

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

Права принимают три значения: allowed — разрешено, partially — только свои объекты, forbidden — запрещено.

У роли есть базовые права на весь аккаунт и, дополнительно, отличия по отдельным папкам: в такой папке действует своё значение, в остальных — базовое. Отличия задаются аргументом folder_permissions у save_workspace_role: аргумент не передан — отличия не меняются, пустой список снимает все. По папкам настраиваются только действия с опросами и самими папками; участники, биллинг, рассылки, файлы, API, почта, шаблоны и темы остаются правами аккаунта целиком.

Что действует у конкретного участника, показывает get_workspace_member_access: общий набор в поле access, отличия — в folder_access (папка, её имя и права, которые действуют именно в ней). Папки, к которым участника не пускают, в отличия не попадают: там они ни на что не влияют.

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

• приглашение отправлено, но человек по нему не перешёл;
• участник не подтвердил почту — до подтверждения ему отказывают независимо от роли;
• у участника ограничен список папок — тогда опросы из других папок он не видит.

Первые две причины get_workspace_member_access называет прямо в поле blocked.

Брендинг воркспейса

Логотип и копирайт — настройки воркспейса, а не отдельного опроса: они действуют сразу на все его опросы, отчёты и PDF. Поэтому у них свои инструменты, а в update_quiz_settings этих полей нет.

update_workspace_branding

Показ логотипа и копирайта.

Нужно передать хотя бы один из двух параметров.

Скрытие копирайта (show_copyright: false) доступно не на всех тарифах — на остальных инструмент вернёт ошибку, а значение останется включённым.

upload_workspace_logo

Загрузка логотипа по ссылке или из base64. Укажите ровно один способ.

Форматы: jpeg, jpg, png, webp. Предел размера — 1 МБ. Свой логотип доступен не на всех тарифах.

delete_workspace_logo

Удаляет логотип воркспейса. Параметр один — workspace_id.

Своё хранилище файлов

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

Два состояния, которые стоит знать:

• Хранилище отвалилось. Запись временно уходит на диск платформы, статус становится fallback. Удачная проверка через verify_workspace_storage возвращает запись обратно; запустить её может только владелец аккаунта.
• Файлы скрыты. Сверх дисковой квоты вложения не удаляются, а скрываются — со стороны автора это выглядит как их пропажа. Раскрывает апгрейд тарифа или оплата; оплату ассистент не проводит.

Идентификатор ключа доступа S3 ассистент видит только последними символами, секрет и токены — никогда.

Две особенности: подсчёт занятого места в своём S3 при первом обращении обходит бакет и может занять несколько секунд, а проверка связи, в отличие от правок настроек опроса, попадает не в журнал правок ассистента, а в журнал хранилища.

manage_workspace_files

Файлы аккаунта: overview, list, delete.

overview — сколько занято, сколько разрешает тариф, разбивка по опросам. list — файлы с фильтрами по опросу, виду медиа, хранилищу и владельцу, с поиском и сортировкой.

Удаление необратимо, а файл респондента приложен к его ответу — после удаления в ответе останется ссылка в никуда. Поэтому confirm_delete обязателен всегда, а не только для режима «все». delete_all вместе со списком файлов отклоняется. Режим «все» уходит очередью, поэтому числа удалённых в ответе нет — приходит queued: true. Загрузка файлов и скачивание архивом недоступны.

manage_workspace_domain

Адрес аккаунта: show, set_subdomain, set_type.

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

get_workspace_domain_status

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

Тариф, оплата в опросе, партнёрка, респонденты

Тариф аккаунта

get_workspace_tariff отвечает на вопрос, который стоит за половиной отказов: что именно мешает — кончился лимит, истёк срок или возможности нет в тарифе.

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

Приём оплаты в опросе стоит отдельным признаком features.quiz_payment, а не среди интеграций: тарифная опция у него своя, и раньше он всегда показывался недоступным. Интеграции лежат в features.integrations под своими кодами (google_sheets, telegram, webhook и остальные).

Только чтение: сменить тариф или оплатить через ассистента нельзя.

Список тарифов

get_tariff_list показывает все тарифы с ценами, периодами и составом. Нужен, когда упёрлись в «недоступно на текущем тарифе»: по списку видно, какой тариф решает задачу. Цены считаются с учётом текущего тарифа — доплата при переходе уже учтена.

Только чтение: оплатить или сменить тариф через ассистента нельзя.

manage_quiz_payment

Приём оплаты в опросе через ЮKassa: show, save.

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

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

get_respondent_campaigns

Заказанные респонденты: кампании закупки прохождений и их результат. Только чтение.

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

Партнёрская программа

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

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

Метки партнёрских источников

manage_partner_source заводит, переименовывает и удаляет метки: create, rename, delete. Название — от 3 до 25 символов; при create без названия подставляется имя по порядку, как в кабинете.

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

Промокоды

Промокоды (Доступно на платных тарифах)

create_promocode_group

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

{
  "content": [{"type": "text", "text": "Список промокодов создан."}],
  "isError": false,
  "list_id": 10
}

add_promocodes

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

{
  "content": [{"type": "text", "text": "Промокоды успешно добавлены."}],
  "isError": false,
  "added_count": 5
}

manage_promocode_group

Правит списки промокодов: update (название, вид и размер кода), delete, attach, detach, delete_code.

Завести список и досыпать кодов — это create_promocode_group и add_promocodes. Удаление списка уносит все его коды и требует confirm_delete. Промокоды доступны не на всех тарифах.

get_promocode_list_quizzes

Показывает, к каким опросам аккаунта привязан список промокодов.

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

Чтение данных: get-инструменты

Чтение данных (Get tools)

Эти инструменты являются полными аналогами ресурсов (Resources) для клиентов, не поддерживающих resources/read.

get_user_me

Возвращает информацию о текущем авторизованном пользователе. Параметры не требуются.

get_workspace_list

Возвращает список рабочих пространств. Параметры не требуются.

get_folder_list

Возвращает список папок текущего пользователя. Параметры не требуются.

get_quiz_list

Возвращает список опросов аккаунта. Без параметров — все живые опросы, как раньше.

Архивные опросы в обычный список не попадают: их показывает archived: true. У каждого опроса есть признак is_archived.

get_quiz_structure

get_quiz_answers

get_quiz_hidden_options

get_quiz_texts

get_quiz_variables

get_quiz_summary

Ответ приходит в одной из двух форм — по формату опроса.

Обычный опрос (type = regular) — как раньше: визиты, устройства, география, воронка по дням.

Опрос на сайте (type = micro) показывается карточкой внутри чужой страницы и своей страницы не имеет, поэтому визитов у него нет и обычная сводка отдала бы нули. Вместо неё приходит воронка показов:

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

{ "quiz_type": "micro", "is_connected": false }

get_quiz_report

get_quiz_widgets_hidden

get_quiz_report_filters

get_quiz_report_files

get_quiz_report_inputs

get_theme_list

Возвращает список тем оформления. Аналог theme://list. Параметры не требуются.

get_theme_details

get_promocode_list

get_promocode_codes