Справочник

Доступ для агентов

Кабинетом можно управлять не только руками в интерфейсе, но и программно — из кода или прямо из ИИ-клиента. Это для тех, кто автоматизирует сборку: разработчиков и вайбкодеров, работающих с ИИ-агентами. Доступны два пути — REST API (/api/v1) для прямых запросов и MCP-сервер для подключения к ИИ-клиенту. Оба дают те же возможности, что и конструктор.

Обзор

Через API и MCP агент делает то же, что человек в конструкторе: создаёт программы, добавляет блоки и связи, настраивает проекты и триггеры. Вся логика и проверки — на стороне МираБотов, поэтому некорректную схему система просто не примет.

Главное отличие от ручной работы — модель черновиков: созданная агентом программа по умолчанию выключена (черновик) и не запускается, пока её не опубликует человек. Так автоматическая сборка остаётся безопасной — агент готовит схему, а решение «запустить» остаётся за вами.

Подключаем агента: по шагам

Всё подключение — это один раз создать ключ в кабинете и вставить его в ИИ-клиент. Куда идти и что нажимать:

  1. Откройте настройки. В левом меню кабинета нажмите «Настройки», затем вверху страницы — вкладку «API» (иконка ключа). Прямой адрес: /cabinet/settings/api.
  2. Создайте ключ. В карточке «Ключи API» нажмите «Новый ключ». Откроется окно с формой:
    • Название — любое понятное вам, например «Агент-сборщик». Нужно только чтобы отличать ключи в списке.
    • Область — Весь кабинет или Отдельный проект. Если выбрать проект, появится поле «Проект» — ключ будет заперт в нём.
    • Уровень доступа — Полный (чтение + запись), Только чтение или Только статистика.
    • Только выключенные схемы (черновики) — галочка (видна при полном уровне): агент сможет править лишь черновики и не сможет публиковать живые схемы.
  3. Нажмите «Сгенерировать». Форма закроется, и поверх страницы откроется окно «Ключ создан»: его трудно пропустить. Закрыть его можно только кнопкой (Esc и щелчок мимо окна не работают — так ключ не потеряется). Сам ключ показывается один раз — повторно увидеть его нельзя, только отозвать и создать новый.
  4. Скопируйте. Нажмите «Скопировать ключ» (сохраните его в надёжном месте) — а ещё удобнее «Скопировать подсказку»: это готовый текст для ИИ-клиента с уже подставленными адресом MCP-сервера и вашим ключом. Закончив, нажмите «Ключ скопирован» — окно закроется, а новый ключ появится в списке.
  5. Вставьте в ИИ-клиент. Отдайте скопированную подсказку своему агенту (или вставьте адрес и ключ в настройки MCP вручную — см. ниже). Готово: агент подключён к кабинету.

Адрес MCP-сервера всегда показан в карточке «Подключение агента к MCP» на той же вкладке — его можно взять и отдельно от создания ключа.

Ключи и уровни доступа

Доступ выдаётся ключами. Ключи создаются и отзываются вручную на вкладке «API» настроек кабинета (см. шаги выше); ключ показывается один раз при создании — сохраните его сразу.

У каждого ключа есть:

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

Агент всегда видит границы своего ключа и не пытается делать запрещённое — лишнее система отклонит.

Подключение MCP-сервера

MCP — протокол, которым инструменты подключаются к ИИ-клиенту (например, к ассистенту-кодеру). Подключив MCP-сервер МираБотов, агент получает набор инструментов для сборки схем прямо из диалога.

Для подключения в ИИ-клиенте указывают две вещи, обе есть в карточке «Подключение агента к MCP» на вкладке «API»:

Проще всего не настраивать это руками, а на шаге создания ключа нажать «Скопировать подсказку» — в ней адрес и ключ уже подставлены, остаётся отдать её агенту.

Дальше агент работает по простому порядку: первым делом вызывает словарь возможностей (describe_capabilities) — он возвращает уровень доступа ключа, правила кабинета и актуальный набор блоков. Затем создаёт программу, добавляет блоки, задаёт их поля, соединяет блоки и назначает триггеры. Готовую схему можно собрать «в памяти» и прислать одним вызовом.

Справочник API

REST API доступен по адресу /api/v1, запрос авторизуется передачей ключа, ответы — в формате JSON. Коротко о возможностях:

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

Страницы проекта через API и MCP

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

Что умеет агент

Действие REST MCP-инструмент
Список страниц GET /pages list_pages
Страница целиком GET /pages/{id} get_page
Дерево от страницы вниз GET /pages/{id}/tree get_page_tree
Проверить, что увидит участник GET /pages/{id}/render preview_page
Создать POST /pages create_page
Изменить PATCH /pages/{id} update_page
Перенести по дереву POST /pages/{id}/move move_page
Удалить DELETE /pages/{id} delete_page
Переставить порядок пачкой POST /pages/reorder — (только REST)
Прочитать меню проекта GET /projects/{id}/menu get_project_menu
Сохранить меню проекта PUT /projects/{id}/menu set_project_menu

Порядок сборки раздела: create_page → запомнить code из ответа (вида pages/page7) → update_page для доработки → preview_page для проверки → set_project_menu, чтобы страница появилась у участников.

Главное: проверка без браузера

preview_page (в REST — GET /pages/{id}/render; параметр uid — внутренний ID пользователя, cond_only=1 — только вердикт условия) отдаёт готовый HTML с подставленными переменными и отдельным полем allowed — вердикт условия показа.

Это то, чего нет у блоков программ: агент пишет текст с {res.7.val}, {list.24.has}, {pageback} и сразу видит результат от имени конкретного пользователя. Если условие не выполнено, в ответе придёт fail_text — ровно тот текст, который увидит человек вместо страницы. Полезно и для отладки: cond_only=1 вернёт только вердикт, без рендера содержимого.

Дерево и защита от ошибок

Страницы вкладываются друг в друга через parentId. Агент может перестроить структуру одним вызовом move_page, но зациклить её не получится: сервер откажет, если родителем выбрана страница изнутри собственного поддерева или она сама.

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

Кто может публиковать

Ключ с флагом «только выключенные схемы (черновики)» работает и со страницами: он может создавать и править страницы со status=0, но не может включить страницу или изменить уже включённую. Проверка та же, что у программ, — публикует человек.

Меню проекта

У проекта есть режим меню — флажок «Своя настройка меню» (custom). Выключен: меню строится само из активных страниц проекта, первая страница верхнего уровня стартовая, сохранённое дерево не используется. Включён: действует дерево, записанное через set_project_menu. get_project_menu возвращает custom, сохранённое menu и effective_menu — то, что участники видят прямо сейчас; set_project_menu с деревом сам включает режим (иначе записанное меню не применилось бы). Режим можно поменять и без дерева, передав только custom (на уровне REST API).

get_project_menu возвращает текущее дерево пунктов и список available_pages — коды, которые можно использовать в пунктах. Для страницы это её code (pages/page7), для внешнего ресурса — type: external и полный http(s)-адрес.

set_project_menu заменяет дерево целиком; валидация та же, что в кабинете: неизвестные коды и небезопасные адреса отбрасываются, стартовой страницей (home: true) может быть только одна внутренняя. Поэтому проще прочитать меню, поправить нужный пункт и записать обратно — не собирая дерево с нуля.

UTM-метки через API

Агент может собрать рекламную ссылку и потом посмотреть, что она принесла. Две задачи — две пары методов.

Ссылки на приложения

GET /projects/{id}/links (MCP: get_app_links) отдаёт для каждой подключённой интеграции проекта:

Поле Что это
webapp_url адрес мини-приложения — его вставляют в настройках бота
utm_base база для меток: https://…/wparams/{integration_id}
public_url ссылка на самого бота или приложение
utm_supported принимает ли эта платформа метки
p_base база для запуска программы при входе: {utm_base}?p=

Ссылка с метками собирается добавлением параметров к utm_base:

{utm_base}?utm_source=vk_ads&utm_medium=cpc&utm_campaign=sale

Агенту не нужно знать формулу /wparams/{id} и различия платформ — они уже учтены внутри.

Запуск программы при входе

Иногда нужно, чтобы при переходе в приложение сначала что-то произошло (начислить бонус, записать в список), а уже потом открылась страница. Для этого в ссылку добавляется параметр p:

{utm_base}?p=<программа>:<стартовый блок>:<подпись>[:<текст>]

Например, ?p=5:1:96lHLrIUAHBBUWKu:Бонус. Всё в одном параметре — подпись и текст идут через двоеточие, поэтому текст может содержать любые символы, включая двоеточия (он берётся до конца строки). В журнале проходов такой запуск помечается типом webapp_open — его легко отличить от нажатия кнопки.

Подпись sig обязательна. Без неё сервер отклонит вызов: иначе можно перебрать номера программ и запустить чужую. Подпись привязана к кабинету, программе и стартовому блоку — но не к человеку, потому что ссылка публичная и её пересылают. Генерируется на сервере, вручную её считать не нужно: в ответе programs[].starts[] уже есть готовое поле sig.

Текст text — необязательный. Попадает в программу как {text}, Length limit — 2000 символов.

Как агент узнаёт, что подставить: в ответе links есть массив programs — опубликованные программы проекта со списком их стартовых блоков:

"programs": [
  {"program_id": 5, "title": "Входящее сообщение",
   "starts": [{"node": "1", "title": "Начало", "sig": "96lHLrIUAHBBUWKu"}]}
]

Можно сразу попросить готовую ссылку — передать p в запрос:

GET /projects/2/links?p=5:1&text=Бонус

Тогда у каждой ссылки появится поле p_url — её и вставляют в рекламу. В MCP это get_app_links(projectId, p).

Проверки: программа должна принадлежать этому проекту и быть опубликованной, а блок — быть настоящим стартовым. Иначе 400 (неверный формат) или 404 (не найдено). Подписи у такой ссылки нет намеренно: она публичная, её пересылают. Защита — в этих проверках.

Если программа упадёт, человек всё равно попадёт на страницу — ошибка уйдёт в журнал, а не на экран. Он пришёл за контентом, а не за отладкой.

Метки и статистика

Задача API MCP
Список меток GET /projects/{id}/utm get_project_utm
Сводка по источникам и кампаниям GET /projects/{id}/utm/stats get_project_utm с stats=true

Фильтры списка: from, to (даты), campaign, source, user_id, limit.

Важно про user_id

В метках user_id — внутренний идентификатор пользователя (sn_users.id, он же sn_int_users.id). Это не участник мероприятия и не id из внешней сети. Тот же идентификатор используется в программах и ресурсах, поэтому метки легко сопоставить с данными человека.

Чего агент сделать не может

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

Внешние расчётные модули (ВРМ)

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

Агенту доступно всё, чтобы собрать ВРМ самостоятельно: в словаре возможностей описан контракт модуля и перечислены готовые примеры, один инструмент возвращает исходник примера как шаблон, другой — опрашивает модуль и отдаёт его поля и выходы, чтобы блок настроился автоматически. Подробнее про сам блок — в разделе «Программы».