База знаний GetMyBot

MCP: программный интерфейс

Как подключить ИИ-ассистента к GetMyBot, чтобы он читал настройки и выполнял задачи по вашему поручению. Доступ, инструменты и технический справочник MCP.

На этой странице

MCP (Model Context Protocol) позволяет подключить к GetMyBot ИИ-ассистента, например для задачи «Покажи мои боты и найди реакцию на /start». Ассистент получает набор инструментов: прочитать настройки, создать реакцию, посмотреть статистику. Он выполняет операции через API с правами вашего токена.

Для подключения укажите адрес /mcp и персональный токен. Если клиент уже работает с REST API, можно использовать тот же токен. Ниже описаны подключение, права и справочник доступных операций. В MCP операция называется инструментом, документ для чтения – ресурсом, а готовая постановка задачи ассистенту – промптом.

Адрес и авторизация

MCP доступен по адресу /mcp, метод POST, транспорт Streamable HTTP. Передавайте заголовок Authorization: Bearer <ПЕРСОНАЛЬНЫЙ_ТОКЕН>. Вместо заполнителя укажите токен целиком, включая mbp_…. Один PAT подходит и для REST, и для MCP.

Токен связан с одним кабинетом: list_bots возвращает его ботов, а get_balance, get_transactions и connect_bot работают с тем же кабинетом. Подробнее: Кабинет токена. Каждый инструмент требует области доступа, как соответствующий запрос REST. Область * разрешает весь публичный набор операций, но не добавляет прав владельцу токена. Если разрешения нет, вызов отклоняется.

Если токен выпущен для чужого кабинета, инструменты уровня кабинета проверяют ещё и права кабинета владельца токена: connect_bot требует bots.create, инструменты биллинга: billing.read или billing.write. Scope * прав кабинета не даёт. Если прав нет, инструмент возвращает ошибку permission denied: missing cabinet right (участника в кабинете нет, кабинет доступен только через расшаренного бота) или permission denied: missing cabinet right: <право> (у участника нет конкретного права). Права выдаёт владелец кабинета в карточке «Доступ к кабинету»; сами операции доступа по MCP недоступны.

Подключение к Claude Code / Cursor

Самый короткий путь: откройте Аккаунт → Персональные токены и создайте токен. Сразу после создания там показан готовый конфиг и команда claude mcp add с уже подставленным токеном; их можно скопировать как есть. Конфиг виден один раз, вместе с токеном.

Нужен именно персональный токен (mbp_…). API-токены проекта (mb_live_…) из настроек проекта работают только с REST API этого проекта: с ними /mcp ответит 401 и подскажет, какой токен нужен.

Если собираете конфиг вручную, используйте адрес своего кабинета (например, https://getmybot.dev/mcp) и вместо <ПЕРСОНАЛЬНЫЙ_ТОКЕН> вставьте токен целиком, вместе с префиксом mbp_:

{
  "mcpServers": {
    "mybot": {
      "url": "https://getmybot.dev/mcp",
      "headers": {
        "Authorization": "Bearer <ПЕРСОНАЛЬНЫЙ_ТОКЕН>"
      }
    }
  }
}

Claude Code: положите этот блок в .mcp.json проекта или добавьте сервер командой:

claude mcp add --transport http mybot https://getmybot.dev/mcp --header "Authorization: Bearer <ПЕРСОНАЛЬНЫЙ_ТОКЕН>"

Cursor: добавьте тот же блок в настройки MCP (Settings → MCP → Add server). После подключения клиент получит список инструментов, ресурсов и промптов автоматически. Если в ответ приходит 401, проверьте, что после Bearer стоит персональный токен целиком, а не API-токен проекта.

Инструменты по доменам

Ниже указаны инструменты и требуемые области доступа (scopes). Имена используют формат глагол_существительное (snake_case). Доступные инструменты зависят от версии сервера: актуальный список возвращает tools/list.

Боты (bots)

  • list_bots: bots:read
  • get_bot: bots:read
  • validate_bot_token: bots:write
  • connect_bot: bots:write
  • update_bot: bots:write
  • delete_bot: bots:write
  • sync_bot: bots:write
  • change_bot_token: bots:write
  • transfer_bot: bots:write
  • get_bot_settings: settings:read
  • update_bot_settings: settings:write (в том числе test_user_ids – тестовые пользователи без списаний)
  • get_widget_email_readiness: settings:read. Передайте bot_id, чтобы проверить настройки email-ответов виджета. senderConfigured показывает, найден ли адрес отправителя; transportStatus принимает значения configured, not_configured или unknown. Это состояние конфигурации, а не подтверждение доставки.
  • get_widget_settings: settings:read
  • update_widget_settings: settings:write

В версиях сервера, где они есть в tools/list, владелец проекта может вызвать reveal_widget_identity_secret или rotate_widget_identity_secret с bots:write, указав bot_id и channel_id. Ротация дополнительно требует confirm_breaking_rotation: true: прежний секрет перестаёт работать сразу, поэтому обновите его на своём сервере. Секрет передаётся MCP-клиенту в открытом виде и может сохраниться в истории клиента; обращайтесь с ним как с паролем.

get_widget_settings возвращает оформление, кнопку открытия, окно чата, приветствие, форму перед чатом, расписание, поведение, разрешённые сайты (origins), ключ widgetKey и номер редакции revision. Для сохранения передайте этот номер как expected_revision в update_widget_settings. Если настройки уже изменил другой человек, сохранение будет отклонено. Не заменяйте этот вызов общим update_bot_settings: запись widget_experience через него не выполняет те же проверки структуры, принадлежности аватара боту и совпадения редакции.

Каналы и WhatsApp-шаблоны (bots)

Через MCP можно управлять Telegram, WhatsApp, VK и виджетом на сайте. Чтение каналов и шаблонов требует области доступа bots:read, изменение требует bots:write. Отдельного разрешения только на каналы нет.

  • list_channels: bots:read: список каналов бота (platform tg/wa/vk/web, external_id, name, enabled, callback_url).
  • connect_channel: bots:write: подключить канал WhatsApp, VK или веб-виджет (platform + creds; для platform: "web" creds не нужны – вместо них обязательный непустой origins).
  • delete_channel: bots:write: отключить канал.
  • list_wa_templates: bots:read: каталог WhatsApp-шаблонов канала (name, language, status, category, body).
  • sync_wa_templates: bots:write: пересинхронизировать каталог шаблонов из Meta.
  • create_wa_template: bots:write: создать WhatsApp-шаблон и отправить на модерацию Meta.
  • update_wa_template: bots:write: изменить шаблон (в статусах APPROVED/REJECTED/PAUSED).
  • delete_wa_template: bots:write: удалить шаблон.

Telegram-каналы подключаются через connect_bot, а не connect_channel: последний рассчитан на wa, vk и web. Категории шаблонов: MARKETING / UTILITY / AUTHENTICATION. create_wa_template сразу отправляет черновик на модерацию Meta; статус меняется асинхронно: читайте его через list_wa_templates (при необходимости обновив каталог sync_wa_templates).

Ответ connect_channel для platform: "web" отличается от остальных платформ: {"widget_key": "…"}, а не {"id": …}. Вызов идемпотентен – повторное подключение того же бота вернёт тот же ключ, а не заведёт второй виджет. Настройка внешнего вида и поведения виджета – отдельная пара get_widget_settings/update_widget_settings выше, а не connect_channel.

Загрузка медиа-заголовка шаблона (изображение/видео/документ) через MCP пока не поддерживается: только через web-интерфейс или REST POST /api/bots/{botID}/channels/{channelID}/templates/media.

Реакции (reactions)

  • list_reactions: reactions:read
  • get_reaction: reactions:read
  • create_reaction: reactions:write
  • update_reaction: reactions:write
  • delete_reaction: reactions:write
  • import_reactions: reactions:write
  • test_formula: reactions:write: проверить расширенную формулу на примере текста. Поля: bot_id, formula, sample (в REST то же поле называется sample_text). Контекст пустой: ctx и параметры не подставляются, пример текста доступен как {text} / {answer}.
  • reorder_reaction: reactions:write
  • get_reaction_links: reactions:read
  • list_reaction_folders: reactions:read
  • create_reaction_folder: reactions:write
  • update_reaction_folder: reactions:write
  • delete_reaction_folder: reactions:write
  • add_reaction_to_folder: reactions:write
  • remove_reaction_from_folder: reactions:write
  • add_reactions_to_folder: reactions:write

Импорт через import_reactions создаёт реакции, но пропускает медиа: в MCP-контексте нет premium-проверки и Telegram-приёмника для файлов. Если в бандле SamBot есть картинки/видео/документы: используйте полнофункциональный REST-импорт (POST /api/bots/{botID}/reactions/import), он переносит и медиа.

Рассылки (broadcasts)

  • start_broadcast: broadcasts:write (опц. paid, опц. сегмент по меткам)
  • get_broadcast: broadcasts:write: для рассылок, запущенных из реакции через start_broadcast, отчёт включает blocked – события блокировки, атрибутированные рассылке в течение 24 часов после доставки.
  • pause_broadcast: broadcasts:write
  • resume_broadcast: broadcasts:write
  • cancel_broadcast: broadcasts:write

Настройки отправки email

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

Сервер отправки выбирается отдельно для каждого проекта. Доступность рассылок и автоматических писем зависит от настройки соответствующих обработчиков; подключение ящика для ответов и входящая почта настраиваются отдельно. Подробнее о выборе сервера и DNS – в статье Письма с вашего домена.

  • get_email_smtp: settings:read. Передайте bot_id; ответ содержит mode: "platform", если выбран GetMyBot, или mode: "custom" с настройками и version. Пароль не возвращается.

  • put_email_smtp: settings:write. Передайте bot_id, host, port, security (starttls или tls), username, envelope_from и password. При первом подключении не передавайте expected_version; при изменении укажите актуальную version из get_email_smtp как expected_version. Пароль можно опустить, если сервер, порт, шифрование и логин не изменились. Перед сохранением проверяются соединение и авторизация, письмо при этом не отправляется.

  • delete_email_smtp: settings:write. Передайте bot_id и актуальный expected_version, чтобы удалить настройки своего SMTP и выбрать режим GetMyBot. Отправка в этом режиме доступна только при настроенном провайдере региона. При смене режима домены нужно подтвердить повторно.

get_email_smtp также возвращает delivery_workers со статусами journey и newsletter: configured, not_configured или unknown. Это конфигурация ответившего сервера, а не подтверждение состояния очереди или доставки письма. Отдельное поле delivery_workers.newsletter_gate показывает общий допуск массовых рассылок: open, paused или unknown, если состояние не удалось проверить. При paused новые задания и получатели не берутся в обработку, но уже начатые отправки могут завершиться. Другие почтовые отправки эта пауза не останавливает.

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

В версиях сервера, где эти инструменты присутствуют в tools/list, также доступны delete_email_domain (bot_id, domain_id, confirm: true), delete_email_inbound_route (bot_id, route_id, confirm: true) и delete_email_mailbox (bot_id, expected_version, confirm: true). Все требуют settings:write; для ящика дополнительно нужно право администрирования поддержки. Версию ящика сначала получите через get_email_mailbox. Удаление домена может быть отклонено, если его используют рассылки.

Проверка содержимого

validate_content_for_channel (content:read) проверяет сохранённую версию материала для выбранного канала без отправки. Передайте bot_id, document_id, version, актуальную expected_revision и platform. Чтобы проверить конкретного получателя, передайте вместе recipient_id и channel_id; при необходимости добавьте identity_id. Доступных проверенных получателей можно получить через list_content_test_recipients.

Результат содержит snapshot, errors и warnings. При несовпадении ревизии получите текущий материал и повторите проверку. Требуются права доступа к проекту и конструктору, а также применимые проверки безопасности. Доступность инструмента проверяйте через tools/list.

Попапы

list_popups и get_popup требуют popups:read; create_popup_draft, update_popup_draft, set_popup_enabled и delete_popup – popups:write. Доступность конкретных операций и A/B-вариантов зависит от версии сервера; проверьте tools/list после обновления.

Для нового выключенного A/B-черновика передайте в create_popup_draft ab_test: true и от двух до пяти вариантов. До первого включения варианты можно изменить через update_popup_draft; при передаче variants укажите весь нужный список, сохраняя ID существующих вариантов. Включите поп-ап через set_popup_enabled с enabled: true: после успешной проверки варианты фиксируются. Ранее зафиксированные варианты остаются неизменяемыми и после выключения поп-апа. Чтобы удалить попап, сначала получите актуальный updated_at через get_popup, затем передайте его как expected_updated_at вместе с confirm: true в delete_popup. Включённый попап перестанет показываться сразу; исторические события и запись эксперимента сохраняются.

Автоматические цепочки

archive_campaign архивирует цепочку, которая не находится в статусе running, delete_campaign удаляет её вместе с историей. clone_campaign_version копирует выбранную версию в новый черновик той же цепочки, заменяя текущий черновик. Все три операции требуют confirm: true; перед клонированием сохраните нужные правки.

Сохранёнными аудиториями можно управлять через list_broadcast_audiences, create_broadcast_audience и delete_broadcast_audience (для удаления требуется confirm: true). list_reaction_broadcast_recipients показывает получателей с пагинацией, list_reaction_broadcasts – историю рассылок реакции. Просмотр получателей требует subscribers:read и права доступа к диалогам.

Для подготовки аудитории доступны инструменты с областью segments:read:

  • list_audience_segments – bot_id, необязательные limit (1–100, по умолчанию 50) и cursor. Возвращает segments и next_cursor для следующей страницы.
  • get_audience_segment – bot_id и segment_id. Возвращает определение, состояние и рассчитанное число участников.
  • preview_audience_segment – bot_id, definition с version и деревом root, limit от 1 до 20. Возвращает оценку estimated_count, признак точности exact и выборку sample: ID и имена посетителей с очищенными причинами совпадения. Оценка может быть неточной.

Для изменения сегментов нужна область segments:write:

  • create_segment – bot_id, name и definition_json: строка с полным JSON-определением версии 2. Каждый вызов создаёт сегмент; перед повтором проверьте существующий список.
  • update_segment – bot_id, segment_id, expected_revision и хотя бы одно из name или definition_json. Новое определение целиком заменяет прежнее. При конфликте ревизии перечитайте сегмент и согласуйте изменение заново.
  • recompute_segment – bot_id и segment_id. Ответ со статусом pending означает постановку пересчёта в очередь, а не завершённый пересчёт.

Эти вызовы изменяют данные и не принимают поле confirm: выполняйте их только по явному поручению пользователя. Изменение условий или пересчёт могут привести к входу пользователей в сегмент и запустить действующую автоматическую кампанию с таким триггером, в том числе отправку писем. Перед вызовом проверьте связанные кампании.

Нужны право на аналитику бота, доступность сегментов в тарифе и применимые требования 2FA. Найденный segment_id можно использовать при настройке аудитории email-кампании: audience_definition с kind: "segment" и этим segment_id. Эти вызовы только читают или оценивают аудиторию: они не сохраняют сегмент, не запускают рассылку и не подтверждают доставку.

Для рассылок на основе контента MCP поддерживает create_content_broadcast, update_content_broadcast_draft, preflight_content_broadcast, list_content_broadcast_recipients и archive_content_broadcast. Изменение и архивация используют expected_revision; список получателей дополнительно требует subscribers:read и права доступа к диалогам. Для планирования используйте schedule_content_broadcast, для тестовой отправки – test_send_content_broadcast; оба требуют expected_revision и confirm: true. Постановка в очередь не подтверждает доставку.

list_campaign_templates перечисляет доступные шаблоны. instantiate_campaign_template принимает bot_id, template_id и необязательное name, создавая новый черновик без запуска или отправки. Для работы с материалами доступны create_content_template, delete_content_template, clone_content и archive_content; удаление и архивация требуют confirm: true.

Доступность операций зависит от версии сервера. Перед использованием проверьте имена через tools/list. Для чтения нужны campaigns:read, для создания, изменения и смены статуса – campaigns:write, для публикации и повтора – campaigns:publish. Также действуют права проекта, требования тарифа и настройки безопасности.

  1. create_campaign создаёт черновик по bot_id и name. Получите текущую ревизию через get_campaign; версии и содержимое доступны через list_campaign_versions и get_campaign_version.
  2. update_campaign_draft принимает bot_id, campaign_id, expected_revision и draft_json. Последний параметр – строка с полным JSON-объектом черновика: trigger, audience, settings, experiment_id, primary_goal, graph. Сохранение заменяет черновик целиком, пропущенные поля очищаются. При конфликте ревизии перечитайте данные и примените изменения заново.
  3. Запустите get_campaign_preflight, чтобы проверить граф без публикации. publish_campaign_draft публикует версию: передайте актуальную expected_revision и confirm: true. Сохранённая опубликованная версия не изменяется при последующих правках черновика.
  4. set_campaign_status задаёт running, paused или stopped. Для запуска running обязательно confirm: true; первый запуск неопубликованной цепочки публикует черновик. Для email-цепочки при таком запуске дополнительно нужны scope campaigns:publish и право публикации. Пауза останавливает вход новых участников, но текущие прохождения продолжаются; stopped останавливает прохождения.
  5. retry_campaign_journey повторяет неудавшийся шаг для subscriber_id и run_no. Укажите bot_id, campaign_id и confirm: true; повтор доступен только для прохождения со статусом ошибки.

list_campaign_failures (campaigns:read) возвращает последние неудачные прохождения цепочки. Передайте bot_id, campaign_id и необязательный limit от 1 до 500 (по умолчанию 100). Курсора нет; при достижении предела список может быть неполным. Сырой текст ошибки не возвращается: используйте error_code и get_campaign_journey_trace.

Метки (labels)

  • list_labels: labels:read
  • create_label: labels:write
  • delete_label: labels:write
  • set_label_favorite: labels:write
  • assign_user_label: labels:write – назначить метку подписчику (tg_user_id) по каноническому UUID label_id, необязательно на срок ttl_days от 0 до 106751 дня; 0 означает постоянную метку, по истечении срока метка снимается и срабатывает событие «Метка истекла»
  • remove_user_label: labels:write – снять метку с подписчика по каноническому UUID label_id

Коллекции и записи (collections)

  • list_collections: collections:read
  • create_collection: collections:write
  • update_collection: collections:write
  • delete_collection: collections:write
  • list_records: collections:read
  • search_records, related_records: collections:read – поиск и связанные строки с метаданными полноты результата
  • create_record: collections:write
  • update_record: collections:write
  • delete_record: collections:write
  • update_record_if: collections:write – атомарно изменить одну запись при совпадении непустого набора ожидаемых полей; результат updated, conflict или not_found

Обработка данных и переходы

  • get_workflow_guide: reactions:read – текущие схемы новых действий, ограничения, результаты и примеры композиции
  • transform_list: reactions:read – фильтры, стабильная сортировка, удаление повторов, окно строк и проекция полей
  • aggregate_list: reactions:read – группировка и именованные итоги по переданным строкам
  • evaluate_conditions: reactions:read – проверить упорядоченные условия и узнать выбранный переход без его выполнения

Эти проверки не требуют коллекции: данные можно передать обычным JSON в data. Они не выполняют реакций и не изменяют состояние бота. Условное изменение update_record_if, напротив, является настоящей записью и попадает в журнал изменений. Указывайте bot_id и нужный region; права кабинета также проверяются.

Действия реакций используют source как ключ контекста, а инструменты проверки списков получают сами данные. Итоги относятся к loaded_rows, не ко всей внешней базе или коллекции. Параметры, результаты и примеры.

Сценарии (flows)

  • list_flows: flows:read
  • get_flow: flows:read
  • create_flow: flows:write
  • update_flow: flows:write
  • delete_flow: flows:write

Интеграции, подключения, доступы (integrations)

  • list_integrations: integrations:read
  • get_integration_sheets: integrations:read
  • get_integration_status: integrations:read
  • create_integration: integrations:write
  • update_integration: integrations:write
  • delete_integration: integrations:write
  • rotate_integration_token: integrations:write
  • list_connections: integrations:read
  • create_connection: integrations:write
  • test_connection: integrations:write
  • update_connection: integrations:write
  • delete_connection: integrations:write
  • list_credentials: integrations:read
  • create_credential: integrations:write
  • update_credential: integrations:write
  • delete_credential: integrations:write

CRM (crm)

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

  • list_crm_connections: crm:read: подключения бота с провайдером, статусом и возможностями.
  • get_crm_connection: crm:read: безопасная сводка одного подключения.
  • get_crm_mapping: crm:read: текущая ревизия маппинга подключения.
  • list_crm_operations: crm:read: последние операции синхронизации, новейшие первыми, при желании в рамках одного подключения.
  • get_crm_operation: crm:read: одна операция с её задачами; сырой полезной нагрузки запроса задачи не отдаёт.
  • list_crm_conflicts: crm:read: задачи, ждущие ручного разбора конфликта.

Что такое подключение, маппинг и операция: на странице CRM-интеграции.

Для настроенной интеграции Ozma Gogol владелец проекта может управлять привязкой контакта чата. Все вызовы требуют bot_id и subscriber_id и действуют только от имени владельца проекта:

  • get_ozma_chat_binding: области crm:read и subscribers:read. Возвращает текущую привязку, revision, кандидатов, truncated и краткоживущий evidence_token.
  • confirm_ozma_chat_binding: области crm:write, crm:read, subscribers:read, subscribers:write; дополнительно contact_id выбранного кандидата, expected_revision и неизменённый evidence_token из последнего чтения. Вызывайте только после явного подтверждения владельца и сверки контакта. Усечённый список подтвердить нельзя, устаревшие данные требуют нового чтения.
  • revoke_ozma_chat_binding: области crm:write и subscribers:write; дополнительно expected_revision из актуального чтения. Отзывает привязку.

Поиск использует email профиля, а при его отсутствии – телефон, только если на сервере включён OZMA_CHAT_PHONE_BINDING_ENABLED (по умолчанию выключен). Совпадение номера не подтверждает личность и не объединяет истории. Подтверждение ставит перенос в очередь, а не доказывает доставку. Доступность зависит от версии и конфигурации региона.

Для ошибок заявки из виджета до постановки CRM-задач доступны list_widget_crm_failures (crm:read, bot_id): до 100 последних записей без контактных данных; и retry_widget_crm_failure (crm:write, bot_id, failure_id): повтор после исправления настроек. При повторе проверяются актуальные согласие и конфигурация; ошибки widget_crm_configuration_invalid и widget_consent_required указывают, что нужно исправить настройки или получить новое согласие. Ответ status: "queued" с operation означает постановку в очередь, не доставку в CRM.

При совпадении контакта Bitrix24, amoCRM или RetailCRM в неуспешной задаче виджета вызовите get_widget_crm_contact_candidate с bot_id и job_id (области crm:read и subscribers:read, права на CRM и диалоги). Сверьте найденную карточку с посетителем и получите явное подтверждение владельца. Затем вызовите confirm_widget_crm_contact_candidate с теми же bot_id, job_id, возвращённым remote_id и confirm: true; нужны области crm:write, crm:read, subscribers:read, subscribers:write и права на CRM и диалоги. Контакт и актуальное согласие проверяются повторно. Успешный status: "queued" означает постановку операции в очередь, а не доставку в CRM.

Для настройки заявок виджета используйте активное подключение Bitrix24, amoCRM или RetailCRM. list_widget_crm_pipelines (crm:read, bot_id, connection_id) возвращает pipelines с этапами statuses и current_revision. Чтобы включить или изменить передачу, вызовите set_widget_crm_trigger (crm:write) с теми же идентификаторами, expected_revision из актуального чтения, enabled: true, pipeline_id и status_id выбранного этапа. Для отключения передайте enabled: false и expected_revision; воронка и этап при этом не обязательны. Ответ содержит revision и enabled. Если ревизия изменилась, перечитайте настройки перед повтором. Для RetailCRM pipeline_id – код магазина, а status_id – статус заказа. Поиск телефона может быть неполным: найденную карточку нужно сверить и подтвердить, а при отсутствии результата проверить контакт в CRM и повторить поиск. Абсолютное отсутствие дублей, в том числе созданных вне MyBot, не гарантируется.

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

Воронка заявки должна совпадать с уже выбранной воронкой CRM-сопоставления: переход на другую воронку этим вызовом не выполняется. Остальные сопоставления сохраняются. Для других CRM это включение пока недоступно.

Браузерный пуш и клиентский SDK (web_push, customer_sdk)

Через MCP можно включить Web Push, менять его конфигурацию и отправлять тестовые уведомления. Ротация секрета личности и отзыв устройства доступны через REST. Инструменты не возвращают приватный ключ VAPID, адрес пуш-подписки, секрет личности или пуш-токен устройства.

  • enable_web_push: web_push:write. Передайте bot_id, subject и navigation_origins, необязательно quiet_hours. При первом включении создаются ключи VAPID; при повторном существующие ключи сохраняются. Нужны права управления Web Push и секретами интеграций, а также применимые требования 2FA; создание ключа ограничено по частоте. Приватный ключ в ответе не возвращается.
  • test_web_push: web_push:write. Передайте bot_id, subscription_id, content_document_id, content_version, payload с содержимым уведомления и обязательное подтверждение confirm: true. Web Push должен быть включён, подписчик должен дать согласие, а версия документа типа push должна быть опубликована. Необходимы право web_push.write и применимая проверка 2FA. Ответ содержит message_id и status: "queued": это постановка в очередь, а не подтверждение доставки. Каждый повторный вызов создаёт новое сообщение.

Для подготовки опубликованного push-документа используйте create_push_content_draft (bot_id, name, необязательные blocks и settings), затем update_push_content_draft (bot_id, document_id, version, expected_revision, необязательное name и полные blocks и settings) и publish_push_content (bot_id, document_id, version, expected_revision). Текущие версию и ревизию можно получить через get_content; документы типа push перечисляет list_content с kind: "push". Для изменений нужен scope content:write, право reactions для участника и применимая проверка 2FA. Создание, изменение и публикация не отправляют уведомление. При обновлении blocks и settings заменяются целиком.

  • update_web_push_config: web_push:write. Передайте bot_id и изменяемые поля: subject, navigation_origins, quiet_hours и/или enabled. Изменяются только переданные поля; ключи VAPID сохраняются. Нужны существующая конфигурация, право управления Web Push и применимые настройки безопасности.
  • get_web_push_config: web_push:read: очищенная конфигурация Web Push для бота.
  • get_web_push_status: web_push:read: включён ли браузерный пуш.
  • get_web_push_report: web_push:read: счётчики подписок и квитанций.
  • list_web_push_subscriptions: web_push:read: до 100 недавних подписок бота. Передайте bot_id; ответ может содержать идентификатор подписчика, сведения о браузере и статус согласия, но не адрес push-сервиса и не ключи.
  • get_customer_sdk_status: customer_sdk:read: включён ли проект мобильного SDK.
  • get_customer_sdk_report: customer_sdk:read: счётчики установок и пуш-токенов.

Для чтения данных Web Push нужно право web_push.read на бота. Для чтения данных клиентского SDK нужно право customer_sdk.read.

Что означают эти числа: на страницах «Пуш в браузере» и «Клиентский SDK».

Ротация ключей VAPID

Для обоих вызовов rotate_web_push_keys нужна существующая конфигурация Web Push, scope web_push:write и право web_push.write. Если проект требует 2FA, владелец токена должен её включить.

  1. Передайте bot_id без confirm или с confirm: false. Ответ содержит число активных подписок в active_subscriptions и confirmation_required: true. Ключи и подписки сохраняются, лимит ротации не расходуется.
  2. Передайте тот же bot_id с confirm: true, если готовы к тому, что активные подписки истекут и затронутым браузерам придётся подписаться заново. Для подтверждения нужно право integrations.secrets и персональный токен (PAT), выпущенный в регионе проекта. Подтверждение расходует общий с REST лимит операций с ключами для этого бота. Ответ содержит config без приватного ключа и фактическое число истёкших подписок в expired_subscriptions.

Инструмент доступен после развёртывания соответствующей версии бэкенда в регионе проекта. Проверьте наличие rotate_web_push_keys в tools/list.

Медиа (media)

  • list_media_assets: media:write. Передайте bot_id, необязательные limit (1–100, по умолчанию 50) и cursor из предыдущего ответа. Возвращает файлы медиатеки, признак использования in_use и next_cursor; вложения чатов и писем в список не входят.
  • delete_media_asset (media:write). Передайте bot_id, asset_id и confirm: true. Нужны право «Реакции» (reactions) и функция тарифа image_storage. Если файл используется, в том числе в базе знаний, инструмент возвращает media_in_use. При успехе запись сразу исчезает из медиатеки (deleted: true). Очистка файла ставится в очередь (blob_cleanup_queued: true) и удаляет файл только при отсутствии других ссылок.
  • upload_media: media:write
  • get_media: media:write
  • download_media: media:write: скачать байты медиа-актива в base64 ({mime, size_bytes, data_base64}), например чтобы перезалить его в другого бота через upload_media. Отказывает на активах крупнее 2 MB.

Если в схеме upload_media из tools/list есть параметр kind со значением launcher_icon, передайте bot_id, kind: "launcher_icon" и байты изображения в Base64 в поле data_base64. Поддерживаются PNG, JPEG и WebP размером до 64 КиБ (65 536 байт). Сервер определяет формат по содержимому файла. Для загрузки нужны media:write, право reactions для участника проекта и функция image_storage на тарифе владельца бота.

Чтобы применить иконку, сохраните возвращённый id в experience.launcher.customIconMediaId через update_widget_settings. Возьмите текущие experience и revision из get_widget_settings, сохраните остальные настройки experience и передайте revision в expected_revision. См. настройку иконки кнопки виджета.

Шаблоны (templates)

  • list_templates: templates:read
  • delete_template: templates:write
  • create_template_from_bot: templates:write
  • apply_template: templates:write

Подписчики, чаты, диалоги (subscribers)

  • list_subscribers: subscribers:read (пагинация offset/limit, поиск, фильтры по меткам и is_blocked=true|false; каждая строка содержит is_blocked и blocked_at, если подписчик заблокировал бота)
  • list_chats: subscribers:read
  • list_dialogs: subscribers:read: треды операторского инбокса: подписчик, платформа, превью последнего сообщения, last_seen; keyset-пагинация через cursor/next_cursor.
  • read_dialog: subscribers:read: сообщения диалога, старые страницы через before_id; у расшифрованных аудио/видео-сообщений в meta приходят transcript_status/transcript/transcript_error.
  • send_dialog_message: subscribers:write: операторская отправка текста подписчику: учитывает 24-часовое окно WhatsApp и маршрутизацию каналов, расход метерится по владельцу токена.
  • send_dialog_attachment: subscribers:write: отправить файл в диалог Telegram, WhatsApp или VK. Передайте bot_id, user_id как строку с числовым ID диалога, file_name, содержимое data_base64 и confirm: true. При необходимости укажите channel_id, content_type, caption и kind. Максимальный размер файла – 16 MiB. Отправка синхронная и не защищена ключом идемпотентности: при тайм-ауте результат может быть неизвестен, поэтому перед повтором проверьте диалог. Для WhatsApp действуют ограничения окна ответа. Инструмент использует канал, сохранённый за диалогом; историческая переписка в другом канале пока недоступна через этот вызов.
  • edit_dialog_message: subscribers:write: Заменяет текст сообщения или поддерживаемую подпись к медиа. Передайте непустое значение text.
  • delete_dialog_message: subscribers:write: Удаляет сообщение. Для подтверждения передайте confirm=true.
  • send_dialog_reaction: subscribers:write: отправить подписчику готовую реакцию бота (как кнопка «отправить реакцию» в операторском чате). REST-аналоги с тем же scope: POST /api/bots/{botID}/users/{userID}/dialog/messages (обязателен Idempotency-Key) и POST /api/bots/{botID}/users/{userID}/dialog/reactions с телом {"reaction_id": "…"}.
  • transcribe_dialog_message: subscribers:write: запустить или получить расшифровку аудио/видео-сообщения. Идемпотентный: первый вызов ставит фоновую задачу ({"status":"pending"}), поллинг повторным вызовом до {"status":"done","text":…}; неудачная расшифровка перезапускается автоматически. Нужна интеграция «Распознавание речи» у бота.

В обоих вызовах передайте bot_id, tg_user_id и id сообщения из read_dialog в параметре message_id. Если нужно уточнить диалог, передайте channel_id и subscriber_id.

Владельцу токена нужно право на диалоги бота (dialogs). Если бот требует 2FA, её нужно включить в аккаунте владельца токена. Доступны только доставленные исходящие сообщения в Telegram, VK и веб-виджете. Возможность изменить или удалить сообщение зависит от канала, типа сообщения и времени с момента отправки.

Инструменты появятся в tools/list после развёртывания обновления бэкенда.

Текстовый ответ в диалоге поддержки

send_support_message ставит ответ в очередь для последнего диалога канонического подписчика. Передайте bot_id, text, канонический subscriber_id и текущую revision из list_support_inbox в expected_dialog_revision. Добавьте confirm: true и idempotency_key в виде UUID в нижнем регистре. Повторяйте запрос с тем же ключом только для той же отправки. Ключ защищает от дублей, пока хранится запись в очереди исходящих сообщений.

Нужны scope support:write, право «Диалоги» (dialogs) и 2FA, если её требует проект. Для email сервер проверяет, что адресат и цепочка писем относятся к этому диалогу. Поле reply_to_message_id принимает ID сообщения для цитаты в поддерживающих каналах. Ответ status: "queued" с новой revision подтверждает постановку в очередь. Доставка подтверждается отдельно.

Чтобы вернуть переданный оператору диалог активному ИИ-агенту, вызовите resume_support_ai_conversation с bot_id, subscriber_id и явным confirm: true; нужна область support:write и права доступа к диалогу. Ответ содержит conversation и resumed; resumed: false означает, что повтор не изменил уже возобновлённый диалог. Если состояние не позволяет возобновление, вызов завершится ошибкой.

Вложения из диалогов поддержки

Чтобы скачать файл, присланный посетителем через виджет сайта, вызовите download_support_widget_attachment с теми же bot_id и subscriber_id, что в вызове read_support_dialog. В message_id передайте числовой id нужного сообщения из ответа.

Токену нужна область support:read, а его владельцу – право на диалоги бота (dialogs). Максимальный размер исходного файла – 20 MiB. В ответе приходят file_name, mime_type, size_bytes и содержимое файла в Base64 в поле data_base64.

Для почтового вложения вызовите download_support_email_attachment с bot_id, subscriber_id, message_id и attachment_id. Идентификатор вложения возьмите из поля id соответствующего элемента массива attachments в сообщении.

Доступность инструментов зависит от развёрнутой версии сервера. Проверьте список в tools/list.

Статус и назначение диалога поддержки

Инструменты статуса диалога и приватных заметок доступны только в версиях сервера, где они развёрнуты, и могут появиться в разное время. Проверьте каждый в tools/list.

  • get_support_dialog_meta · support:read · bot_id, subscriber_id. Возвращает состояние диалога: bot_id, subscriber_id, status, revision, assignee_id, group_id, snoozed_until, last_activity_at, first_inbound_at, first_response_at, last_inbound_at, last_response_at, closed_at, reopened_at, reopen_count и tags (ID тегов). Пустые поля в ответ не попадают. Исторический ID подписчика после объединения приводится к текущему, и в ответе приходит канонический subscriber_id.
  • update_support_dialog_meta · support:write · bot_id, subscriber_id, expected_revision и хотя бы одно изменение: status, snoozed_until, assignee_id, group_id или assign_to_self. Неуказанные поля не меняются. Ответ содержит обновлённое состояние с новой revision.

Правила изменения:

  • status принимает open, pending, closed или snoozed. Значение open переоткрывает закрытый диалог. Из closed можно перейти только в open или snoozed. Передать текущий статус без других изменений нельзя.
  • Для перехода в snoozed укажите snoozed_until: момент в будущем в формате RFC 3339. Поле snoozed_until принимается, только если после изменения диалог будет в статусе snoozed.
  • assignee_id принимает ID участника этого бота, пустая строка снимает назначение. assign_to_self: true назначает диалог владельцу токена и не сочетается с assignee_id.
  • group_id принимает ID группы операторов этого бота, пустая строка убирает группу.

Для записи передавайте bot_id и subscriber_id как канонические UUID: в нижнем регистре и с дефисами. Используйте текущий subscriber_id из get_support_dialog_meta или list_support_inbox. Если подписчика уже объединили с другим, ревизия, полученная для его прежнего ID, не подходит, и сервер вернёт конфликт ревизии. В expected_revision передайте текущую revision из get_support_dialog_meta или list_support_inbox. При ошибке dialog revision conflict прочитайте диалог заново и решите, нужно ли изменение, прежде чем повторить его.

Для чтения токену нужна область support:read, для записи – support:write. Владельцу токена нужно право «Диалоги» (dialogs) на бота, а если проект требует 2FA, она должна быть включена в его аккаунте.

Приватные заметки в диалоге поддержки

Приватные заметки – это внутренние комментарии операторов к диалогу. Подписчику они не отправляются.

  • list_support_private_notes · support:read · bot_id, subscriber_id. Возвращает до 100 активных заметок, сначала новые. В ответе массив notes, у каждой заметки есть id, bot_id, subscriber_id, author_id, body, created_at и edited_at, если её редактировали.
  • create_support_private_note · support:write · bot_id, subscriber_id, body, expected_revision. Добавляет заметку от имени владельца токена и возвращает её.
  • update_support_private_note · support:write · bot_id, subscriber_id, note_id, body, expected_revision. Заменяет текст заметки и проставляет edited_at.
  • delete_support_private_note · support:write · bot_id, subscriber_id, note_id, expected_revision. Удаляет заметку мягко: она помечается удалённой и больше не возвращается в списке. Ответ: {"status": "deleted"}.

body не может быть пустым или состоять только из пробелов, допустимый размер – до 10 000 байт. Все ID передавайте как канонические UUID в нижнем регистре. Исторический subscriber_id после объединения подписчиков приводится к текущему, поэтому в ответе может прийти другой subscriber_id. Для неизвестного диалога или заметки сервер возвращает ошибку «не найдено».

Автором заметки становится владелец токена, его ID приходит в author_id. Создавать заметки могут владелец бота и его участники. Изменить или удалить заметку может только её автор: даже владелец бота не может править чужие заметки.

Каждое создание, изменение или удаление заметки увеличивает ревизию диалога. В expected_revision передайте текущую revision из get_support_dialog_meta или list_support_inbox. Ответ с заметкой новой ревизии не содержит, поэтому перед следующей записью прочитайте диалог заново. При ошибке dialog revision conflict перечитайте диалог и проверьте, актуально ли изменение.

Права те же, что для статуса диалога: support:read для чтения, support:write для записи, право «Диалоги» (dialogs) и 2FA, если её требует проект.

Теги диалогов поддержки

Теги – это общий для бота словарь меток, например «оплата» или «возврат», которыми операторы размечают диалоги. Инструменты появятся только после развёртывания соответствующей версии бэкенда. Проверьте наличие каждого из них в tools/list.

  • list_support_dialog_tags · support:read · bot_id. Возвращает массив tags: словарь тегов бота, отсортированный по name. У каждого тега есть id и name, а также color, если цвет задан.
  • create_support_dialog_tag · support:write · bot_id, name, необязательный color. Пробелы по краям name отбрасываются, пустое имя или имя длиннее 100 символов не принимается. color – строка до 32 символов для отображения, например #ff8800; её формат сервер не проверяет. Возвращает тег с id, name и color.
  • delete_support_dialog_tag · support:write · bot_id, tag_id. Удаляет тег из словаря и снимает его со всех диалогов. Ответ: {"status": "deleted"}.
  • add_support_dialog_tag · support:write · bot_id, subscriber_id, tag_id, expected_revision. Добавляет тег из словаря к диалогу.
  • remove_support_dialog_tag · support:write · bot_id, subscriber_id, tag_id, expected_revision. Снимает тег с диалога.

add_support_dialog_tag и remove_support_dialog_tag возвращают состояние диалога в формате get_support_dialog_meta с актуальным списком tags. Если тег уже добавлен или уже снят, ничего не меняется и возвращается текущее состояние. Если у подписчика ещё нет сохранённого диалога, add_support_dialog_tag создаёт открытый диалог с ревизией 1. Фактическое изменение тегов операторы сразу видят в инбоксе.

В expected_revision передайте текущую revision из get_support_dialog_meta или list_support_inbox. Значение должно быть не меньше 1, иначе сервер вернёт expected_revision is required. Если ревизия диалога уже другая, тег не меняется и возвращается dialog revision conflict: перечитайте диалог через get_support_dialog_meta, возьмите из ответа канонический subscriber_id и revision и решите, нужно ли изменение. Сами теги ревизию не меняют: добавление, снятие и удаление тега не увеличивают revision, не попадают в историю диалога и не сдвигают время последней активности. Поэтому ответ содержит прежнюю revision, и её можно передать в следующий вызов. Проверка ревизии защищает от других изменений диалога после чтения, например статуса, назначения или заметок, но не от параллельной правки тегов другим оператором.

Все ID передавайте как канонические UUID в нижнем регистре с дефисами, иначе сервер вернёт ошибку вида tag_id must be a canonical UUID. tag_id возьмите из list_support_dialog_tags, а subscriber_id – текущий из get_support_dialog_meta или list_support_inbox. В отличие от инструментов чтения, запись тегов не приводит исторический ID объединённого подписчика к текущему и отклоняет его с dialog revision conflict. При объединении подписчиков теги переходят к оставшемуся диалогу.

Тег и подписчик должны принадлежать боту из bot_id. Для чужого или недоступного бота сервер возвращает bot not found, для тега другого бота – dialog tag not found, для подписчика другого бота – subscriber not found; данные других ботов при этом не меняются. Изменять словарь и теги диалогов можно только токеном, выпущенным для кабинета владельца бота. С токеном другого кабинета запись отклоняется с permission denied.

Для list_support_dialog_tags токену нужна область support:read, для остальных инструментов – support:write. С областью только для чтения запись вернёт insufficient scope. Владельцу токена нужно право «Диалоги» (dialogs) на бота, иначе сервер вернёт missing bot right. Если проект требует 2FA, она должна быть включена в аккаунте владельца токена, иначе возвращается two_factor_enrollment_required. При записи токен, область, право и 2FA проверяются ещё раз в той же транзакции. Если токен отозвали или права изменились, ничего не записывается и возвращается permission denied или ошибка «не найдено». Каждая запись попадает в журнал действий с пометкой MCP.

У инструментов нет ключа идемпотентности, поэтому учитывайте поведение при повторе:

  • add_support_dialog_tag и remove_support_dialog_tag можно повторить с той же expected_revision: теги ревизию не меняют, а повтор не создаёт дубликат и возвращает текущее состояние. Если между попытками ревизия изменилась по другой причине, повтор вернёт dialog revision conflict. Перечитайте диалог через get_support_dialog_meta, проверьте tags и используйте возвращённые канонический subscriber_id и revision.
  • Повторный create_support_dialog_tag с тем же name не создаёт копию и возвращает тег с прежним id. Без поля color текущий цвет сохраняется, поэтому повтор безопасен. Явный color заменяет цвет, а пустая строка "" очищает его.
  • Повторный delete_support_dialog_tag вернёт dialog tag not found. Удаление необратимо: тег с тем же именем, созданный заново, получит новый id, и его нужно снова добавить к диалогам.

Быстрые ответы операторов

Быстрые ответы – это шаблоны, которые оператор вставляет в ответ, набрав / и сокращение. Инструменты доступны только в версиях сервера, где они развёрнуты. Проверьте их наличие в tools/list.

  • list_quick_replies · support:read · bot_id. Возвращает массив items: общие шаблоны бота и личные шаблоны владельца токена. Сначала идут самые используемые, при равном счётчике – по shortcut в алфавитном порядке. У каждого шаблона есть id, shortcut, title, blocks и usage_count, у личного также owner_id.
  • create_quick_reply · support:write · bot_id, shortcut, необязательные title, blocks и personal. В shortcut передайте сокращение без /, пустое значение не принимается. blocks – блоки сообщения в формате конструктора реакций: с текстом, кнопками, медиа и теми же подстановками. По умолчанию это пустой список. personal: true создаёт личный шаблон, без него шаблон становится общим для команды. Возвращает сохранённый шаблон.
  • delete_quick_reply · support:write · bot_id, quick_reply_id. Удаляет общий шаблон или личный шаблон владельца токена. Ответ: {"status": "deleted"}.
  • use_quick_reply · support:write · bot_id, quick_reply_id. Отмечает, что оператор вставил шаблон: увеличивает usage_count на 1 и поднимает шаблон в списке. Сообщение подписчику не отправляется. Ответ: {"status": "used"}.

Общие шаблоны видят все, у кого есть право «Диалоги» на бота, и любой из них может удалить общий шаблон. Личный шаблон принадлежит владельцу токена, который его создал: создать личный шаблон за другого участника нельзя. Чужие личные шаблоны не попадают в список даже у владельца бота. Для них, как и для неизвестного или некорректного ID, delete_quick_reply и use_quick_reply возвращают quick reply not found, а счётчик не меняется.

У инструментов нет ключа идемпотентности, поэтому учитывайте поведение при повторе:

  • Повторный create_quick_reply с personal: true и тем же shortcut не создаёт копию. Он заменяет title и blocks существующего личного шаблона, а id и usage_count сохраняются.
  • Повторный create_quick_reply для общего шаблона создаёт ещё один шаблон с тем же shortcut и новым id. Если ответ на создание потерялся, сначала проверьте list_quick_replies.
  • Каждый вызов use_quick_reply увеличивает счётчик ещё на 1. Вызывайте его один раз на одну вставку шаблона.
  • Повторный delete_quick_reply для уже удалённого шаблона вернёт quick reply not found.

Для list_quick_replies токену нужна область support:read, для остальных инструментов – support:write. Владельцу токена нужно право «Диалоги» (dialogs) на бота, а если проект требует 2FA, она должна быть включена в его аккаунте. Без права сервер вернёт missing bot right, без 2FA – two_factor_enrollment_required. При записи токен, область support:write, право и 2FA проверяются ещё раз в той же транзакции. Если токен отозвали или права изменились, запись не выполняется и возвращается permission denied или ошибка «не найдено». Менять шаблоны архивного бота нельзя.

Группы операторов

Группы операторов – это именованные наборы участников бота, на которые маршрутизируются диалоги. id группы передаётся как group_id в update_support_dialog_meta, а также как scope или overflow_group_id в инструменты расписаний и автоответов. Инструменты появятся только после развёртывания соответствующей версии бэкенда. Проверьте наличие каждого из них в tools/list.

  • list_operator_groups · support:read · bot_id. Возвращает массив groups, отсортированный по name. У каждой группы есть id, name, strategy и member_ids: ID аккаунтов участников группы или пустой массив. Порядок member_ids в списке не гарантируется.
  • create_operator_group · support:write · bot_id, name, необязательный strategy. Пробелы по краям name отбрасываются. Пустое имя вернёт name is required, имя длиннее 200 символов – name must be at most 200 characters. Имя уникально в пределах бота. strategy принимает least_busy (по умолчанию), round_robin или all, другое значение вернёт strategy must be least_busy, round_robin or all. Возвращает group и created.
  • delete_operator_group · support:write · bot_id, group_id. Удаляет группу. Ответ: {"status": "deleted", "group_id": "…"}.
  • add_operator_group_member · support:write · bot_id, group_id, owner_id. Добавляет участника бота в группу. Возвращает group и changed.
  • remove_operator_group_member · support:write · bot_id, group_id, owner_id. Убирает аккаунт из группы. Возвращает group и changed.

В ответах на запись group содержит те же поля, что и в списке, а member_ids отсортированы по ID. Когда диалог маршрутизируется на группу, при least_busy он назначается участнику с наименьшим числом открытых назначенных ему диалогов, а при round_robin – участнику, который дольше всех не получал назначений. При all автоматическое назначение сейчас выбирает участника так же, как при least_busy. Переименовать группу или сменить стратегию существующей группы через MCP нельзя.

В owner_id передайте ID аккаунта владельца бота или администратора бота. Для любого другого аккаунта, в том числе аккаунта с приостановленной обработкой данных, add_operator_group_member вернёт owner_id is not a member of this bot. Участник, потерявший доступ к боту, автоматически исключается из его групп. Инструмента для списка участников бота в MCP нет: ID аккаунтов видны в member_ids и в assignee_id из get_support_dialog_meta. remove_operator_group_member членство в боте не проверяет.

Вместе с группой удаляются её правила маршрутизации, её расписание с праздниками и её политики автоответов. Диалоги теряют группу в group_id, но сохраняют назначенного оператора, а расписания, где группа указана в overflow_group_id, теряют эту настройку. Пока активный или приостановленный ИИ-агент передаёт диалоги в эту группу, удаление отклоняется с operator group is the handoff target of an active or paused AI agent: сначала смените группу передачи у агента. Удаление необратимо: группа с тем же именем, созданная заново, получит новый id, и участников, правила и расписание придётся настроить снова.

Все ID передавайте как канонические UUID в нижнем регистре с дефисами, иначе сервер вернёт ошибку вида group_id must be a canonical UUID. Для чужого, архивного или недоступного бота сервер возвращает bot not found, для неизвестной группы или группы другого бота – operator group not found. Менять группы можно только токеном, выпущенным для кабинета владельца бота. С любым другим токеном запись отклоняется с bot not found или permission denied.

Для list_operator_groups токену нужна область support:read, для остальных инструментов – support:write. С областью только для чтения запись вернёт insufficient scope. Владельцу токена нужно право «Диалоги» (dialogs) на бота, иначе сервер вернёт missing bot right. Если проект требует 2FA, она должна быть включена в аккаунте владельца токена, иначе возвращается two_factor_enrollment_required. При записи токен, область, право и 2FA проверяются ещё раз в той же транзакции. Если токен отозвали или права изменились, ничего не записывается и возвращается permission denied или bot not found. Каждая запись попадает в журнал действий с пометкой MCP.

У инструментов нет ключа идемпотентности, поэтому учитывайте поведение при повторе:

  • Повторный create_operator_group с теми же name и strategy не создаёт копию и возвращает существующую группу с created: false. Без strategy используется least_busy. То же имя с другой стратегией вернёт an operator group with this name already exists with a different strategy, а группа не изменится. Эта же ошибка возможна, если группу с таким именем в этот момент удаляют, поэтому перед повтором проверьте list_operator_groups.
  • Повторы add_operator_group_member и remove_operator_group_member безопасны: если аккаунт уже в группе или уже убран, ничего не меняется и возвращается текущая group с changed: false.
  • Повторный delete_operator_group вернёт operator group not found.
  • operator group change conflicted with a concurrent update; retry означает, что ничего не записано и тот же вызов можно повторить. После operator group could not be changed проверьте состояние через list_operator_groups и только потом повторяйте. account processing is suspended означает, что обработка данных аккаунта приостановлена, и повтор не поможет.

Правила маршрутизации поддержки

Правила маршрутизации автоматически назначают новый диалог группе операторов или конкретному участнику бота. Инструменты появятся только после развёртывания соответствующей версии бэкенда. Проверьте наличие каждого из них в tools/list.

  • list_routing_rules · support:read · bot_id. Возвращает массив rules: все правила бота, включённые и выключенные, в порядке проверки. Правила отсортированы по priority, при равном приоритете – по name.
  • create_routing_rule · support:write · bot_id, name, ровно одно из полей group_id и assignee_id, необязательные priority, enabled и match. Каждый вызов создаёт новое правило. Возвращает rule.
  • update_routing_rule · support:write · bot_id, rule_id и хотя бы одно из полей name, priority, enabled, match, group_id или assignee_id. Без изменений сервер вернёт nothing to update. Возвращает обновлённое rule.
  • delete_routing_rule · support:write · bot_id, rule_id. Удаляет правило. Ответ: {"status": "deleted", "rule_id": "…"}.
  • reorder_routing_rules · support:write · bot_id, expected_rule_ids, rule_ids. Задаёт порядок всех правил бота и возвращает массив rules в новом порядке.

У правила есть id, bot_id, name, priority, enabled, match и одно из полей group_id или assignee_id. В match приходят только заданные условия, у правила без условий это {}. Пробелы по краям name отбрасываются. Пустое имя вернёт name is required, имя длиннее 200 символов – name must be at most 200 characters. Уникальность имени не проверяется. priority – целое число в 32-битном диапазоне, в том числе отрицательное: чем меньше значение, тем раньше проверяется правило. Без priority новое правило получает 100, без enabled создаётся включённым. Если create_routing_rule или update_routing_rule возвращает правило с непустым match.tags, ответ содержит ещё массив warnings.

Условия. Все списки в match необязательны, и правило срабатывает, только если выполнены все заданные условия. Без match или с пустым match правило подходит к любому новому диалогу.

  • platforms – каналы, откуда пришло сообщение: tg, vk, wa, web, email, ig или fb. Достаточно совпадения с одним. Значения приводятся к нижнему регистру, другое значение вернёт match.platforms must contain only tg, vk, wa, web, email, ig or fb.
  • keywords – подстроки первого входящего сообщения без учёта регистра. Достаточно совпадения с одной.
  • labels – имена меток подписчика, регистр учитывается. У подписчика должны быть все перечисленные метки.
  • tags – ID тегов диалога этого бота из list_support_dialog_tags. Такое условие никогда не выполняется: маршрутизация срабатывает на первом входящем сообщении, когда тег ещё нельзя добавить. Правило сохраняется, а в warnings приходит предупреждение об этом.

В каждом списке может быть до 50 значений. Значения keywords и labels не могут быть пустыми или состоять из пробелов и ограничены 200 символами. Иначе сервер вернёт ошибку проверки, например match.keywords must have at most 50 entries. Тег другого бота или несуществующий тег вернёт dialog tag not found in this bot.

Цель. В group_id передайте ID группы из list_operator_groups, в assignee_id – ID аккаунта владельца бота или администратора бота. Укажите ровно одно из этих полей, иначе сервер вернёт specify exactly one of group_id or assignee_id. Для группы другого бота или неизвестной группы возвращается group does not belong to this bot, для аккаунта, который не состоит в боте, – assignee is not a member of this bot. Правила группы удаляются вместе с ней, а правила участника – когда он теряет доступ к боту.

Частичное изменение. update_routing_rule меняет только переданные поля. match заменяется целиком: чтобы добавить ключевое слово, передайте весь новый match, а {} снимает все условия. Переданный group_id или assignee_id заменяет цель: прежнее поле очищается, поэтому передавайте только одно из них. Если после изменения цели не останется или их станет две, например при group_id: "" без assignee_id, сервер вернёт specify exactly one of group_id or assignee_id. При смене цели и при enabled: true сервер заново проверяет, что цель относится к боту, а теги проверяет, только если передан match. Ревизии у правил нет: изменение записывается поверх текущего состояния, даже если правило только что изменил кто-то другой.

Порядок. В expected_rule_ids передайте ID всех правил бота, включая выключенные, в текущем порядке из list_routing_rules, а в rule_ids – те же ID в нужном порядке. Без этих полей сервер вернёт expected_rule_ids is required или rule_ids is required. Если rule_ids не совпадает с expected_rule_ids по составу или содержит повторы, возвращается invalid routing rule order: rule_ids must be a permutation of expected_rule_ids. Если после чтения правило добавили, удалили или порядок изменился, вызов ничего не меняет и возвращает routing rules changed; reload and retry. При успехе правила получают приоритеты 10, 20, 30 и так далее. Новое правило с приоритетом по умолчанию 100 встанет после правил с меньшим приоритетом, а при равном приоритете его место определит name.

Как применяются правила. Маршрутизация срабатывает один раз: на первом входящем сообщении диалога, у которого ещё нет ни оператора, ни группы. Сервер проверяет включённые правила по порядку и применяет первое подходящее. Для группы оператор выбирается по её стратегии с учётом расписаний и overflow_group_id. Для участника учитывается расписание бота, а если участник недоступен, диалог может получить другой участник одной из его групп. Если по первому подходящему правилу доступного оператора нет, следующие правила не проверяются и диалог остаётся в очереди неназначенных. Так же происходит, если не подошло ни одно правило. Создание, изменение, удаление и смена порядка правил не затрагивают уже назначенные диалоги: они сохраняют своё назначение.

Все ID передавайте как канонические UUID в нижнем регистре с дефисами, иначе сервер вернёт ошибку вида rule_id must be a canonical UUID. Для чужого, архивного или недоступного бота сервер возвращает bot not found, для неизвестного правила или правила другого бота – routing rule not found. Менять правила можно только токеном, выпущенным для кабинета владельца бота. С любым другим токеном запись отклоняется с bot not found или permission denied.

Для list_routing_rules токену нужна область support:read, для остальных инструментов – support:write. С областью только для чтения запись вернёт insufficient scope. Владельцу токена нужно право «Диалоги» (dialogs) на бота, иначе сервер вернёт missing bot right. Если проект требует 2FA, она должна быть включена в аккаунте владельца токена, иначе возвращается two_factor_enrollment_required. При записи токен, область, право и 2FA проверяются ещё раз в той же транзакции. Если токен отозвали или права изменились, ничего не записывается и возвращается permission denied или bot not found. Каждая запись попадает в журнал действий с пометкой MCP.

У инструментов нет ключа идемпотентности, поэтому учитывайте поведение при повторе:

  • Повторный create_routing_rule создаёт ещё одно правило с новым id, даже если поля совпадают. Если ответ на создание потерялся, сначала проверьте list_routing_rules.
  • Повторный update_routing_rule снова записывает переданные значения. Если между попытками правило изменил кто-то другой, повтор перезапишет эти поля. Если ответ потерялся, сначала проверьте правило через list_routing_rules.
  • Повторный delete_routing_rule вернёт routing rule not found. Удаление необратимо: правило, созданное заново, получит новый id.
  • После успешного reorder_routing_rules повтор с теми же expected_rule_ids обычно вернёт routing rules changed; reload and retry, потому что порядок уже другой. Та же ошибка возникает, если правила изменил кто-то другой. В обоих случаях перечитайте list_routing_rules, проверьте порядок и только потом повторяйте с новым expected_rule_ids.
  • После routing rule could not be changed проверьте состояние через list_routing_rules и только потом повторяйте. account processing is suspended означает, что обработка данных аккаунта приостановлена, и повтор не поможет.

Прочтение операторских диалогов

Эти инструменты работают с теми же счётчиками непрочитанного, что и инбокс операторов: показывают, сколько входящих сообщений владелец токена ещё не прочитал, и отмечают диалог прочитанным, как при его открытии в консоли. Инструменты появятся только после развёртывания соответствующей версии бэкенда. Проверьте наличие каждого из них в tools/list.

  • get_dialog_unread_summary · support:read · bot_id. Возвращает {"items": [...], "count": N}: непрочитанное владельца токена по диалогам бота, включая email. Диалоги без непрочитанных входящих сообщений в ответ не попадают. У строки есть user_id и unread, а также channel_id, scope_channel_id и subscriber_id, если они не пустые. Один пользователь может встретиться в нескольких строках, по одной на канал. Пагинации нет, порядок строк не гарантируется.
  • get_dialog_read_state · support:read · bot_id, user_id, необязательные channel_id и subscriber_id. Возвращает состояние прочтения одного диалога и ничего не меняет.
  • mark_dialog_read · support:write · bot_id, user_id, необязательные channel_id, subscriber_id и last_read_message_id. Отмечает диалог прочитанным для владельца токена и возвращает новое состояние.

Ответ get_dialog_read_state и mark_dialog_read содержит unread (число непрочитанных входящих сообщений), first_unread_message_id (ID самого раннего непрочитанного сообщения в порядке ленты, поля нет, если всё прочитано), last_read_message_id (собственная отметка владельца токена или 0, если он диалог не читал) и shared (true, если для владельца токена действует совместное прочтение).

Как указать диалог. user_id – ID пользователя диалога строкой в десятичной записи. Возьмите user_id из строки сводки или tg_user_id_str из list_dialogs и передайте строкой без изменений: числовой tg_user_id теряет точность у больших ID. Ведущие нули, знак +, экспонента и 0 не принимаются, сервер вернёт user_id must be a non-zero decimal integer string.

Чтобы выбрать диалог из сводки, передайте её scope_channel_id как channel_id, а не поле channel_id строки. В сводке channel_id пуст у старого диалога Telegram без привязки к каналу, а scope_channel_id указывает канал, к которому относятся сообщения и отметка. Для точного выбора добавьте subscriber_id из той же строки. Передавать его без channel_id нельзя: сервер вернёт subscriber_id requires channel_id. Если в строке нет scope_channel_id, не передавайте ни channel_id, ни subscriber_id.

Без channel_id и subscriber_id инструменты работают со старым (legacy) диалогом в основном Telegram-канале бота, как адрес консоли без канала. Это та же отметка, что и с channel_id этого Telegram-канала. В list_dialogs ID канала нет, поэтому по одному tg_user_id_str доступен только такой диалог. Диалоги одного пользователя в разных каналах читаются отдельно: отметка в одном канале не меняет счётчик в другом.

UUID передавайте в каноническом виде: в нижнем регистре и с дефисами, иначе сервер вернёт ошибку вида channel_id must be a canonical UUID. Если канал принадлежит другому боту, у пользователя нет диалога в этом канале, subscriber_id относится к другому диалогу или подписчик уже объединён с другим, возвращается dialog scope not found. После объединения подписчиков заново получите строку из сводки. invalid dialog scope означает некорректное сочетание channel_id и subscriber_id.

Отметка прочтения. Без last_read_message_id или с 0 диалог отмечается прочитанным полностью на момент вызова. Чтобы отметить прочтение до определённого места, передайте id сообщения этого диалога, например из read_dialog: более поздние сообщения в порядке ленты останутся непрочитанными. Сообщение другого диалога или канала вернёт message not found in this dialog, отрицательное значение – last_read_message_id must not be negative. Отметка двигается только вперёд: если переданное сообщение раньше текущей отметки, она не меняется и возвращается текущее состояние.

Отметка принадлежит владельцу токена, а не владельцу бота, и меняет только его счётчики. Клиенту ничего не отправляется, отчёт о прочтении не передаётся, сообщения и статус диалога поддержки не меняются. Если отметка сдвинулась, открытые консоли операторов обновляют счётчики.

Совместное прочтение. Если совместное прочтение включено для всего бота или в личных настройках владельца токена (см. Поддержка), unread, first_unread_message_id и сводка считаются от последней отметки любого оператора, а shared равно true. last_read_message_id и в этом режиме остаётся собственной отметкой владельца токена. Поэтому mark_dialog_read может снять счётчик и у коллег, для которых действует совместное прочтение. Без него отметка влияет только на владельца токена.

Доступ и ошибки. Для get_dialog_unread_summary и get_dialog_read_state токену нужна область support:read, для mark_dialog_read – support:write. С областью только для чтения отметка вернёт insufficient scope. Владельцу токена нужно право «Диалоги» (dialogs) на бота, иначе сервер вернёт missing bot right. Если проект требует 2FA, она должна быть включена в аккаунте владельца токена, иначе возвращается two_factor_enrollment_required. Для чужого, архивного или недоступного бота возвращается bot not found. Отмечать прочтение можно только токеном, выпущенным для кабинета владельца бота, с другим токеном запись отклоняется с bot not found или permission denied. При отметке токен, область, право и 2FA проверяются ещё раз в той же транзакции. Если токен отозвали или права изменились, ничего не записывается и возвращается permission denied или bot not found. Каждый вызов mark_dialog_read, в том числе отклонённый, попадает в журнал действий с пометкой MCP. Чтение в журнал не пишется.

Ошибки unread summary is temporarily unavailable, dialog read state is temporarily unavailable и dialog could not be marked read временные. У mark_dialog_read нет ключа идемпотентности, но повтор безопасен: отметка не двигается назад, а повтор с тем же last_read_message_id ничего не меняет. Повтор без last_read_message_id отметит и сообщения, пришедшие между попытками.

Расписание, праздники и автоответы поддержки (support)

Проверьте наличие инструментов в tools/list после обновления сервера. Владельцу персонального токена нужно право «Диалоги» (dialogs). Если проект требует 2FA, включите её в аккаунте владельца токена.

Во всех вызовах передавайте bot_id. Для scope укажите bot или UUID группы операторов этого бота.

  • list_support_schedules · support:read · bot_id. Список расписаний бота и его групп с ревизиями.
  • list_support_holidays · support:read · bot_id, scope. Список праздников выбранного расписания и его текущая ревизия.
  • list_support_auto_replies · support:read · bot_id. Список правил автоответов бота и его групп с ревизиями.
  • preview_support_availability · support:read · bot_id, scope, from, to. Показывает состояние на момент from и переходы по сохранённому расписанию и праздникам до to. Передайте даты и время в формате RFC 3339. Период должен быть больше нуля и составлять не более 31 дня. Инструмент ничего не сохраняет и не отправляет. В ответе до 512 записей transitions с полями at, state и reason.
  • upsert_support_schedule · support:write · bot_id, scope, timezone, weekly_intervals, enabled, expected_revision. Создаёт или заменяет расписание. Передайте часовой пояс IANA, например Europe/Belgrade, и полный список недельных интервалов. В каждом интервале укажите weekday (0 – воскресенье, 6 – суббота), start_minute и end_minute в минутах от полуночи по местному времени. Необязательный overflow_group_id указывает группу этого же бота.
  • replace_support_holidays · support:write · bot_id, scope, holidays, expected_revision. Заменяет весь список праздников существующего расписания. Для каждой записи укажите local_date (YYYY-MM-DD), kind (closed или custom), name и intervals. Для closed передайте пустые интервалы, для custom – интервалы с start_minute и end_minute. Чтобы очистить список праздников, передайте holidays: [].
  • upsert_support_auto_reply · support:write · bot_id, scope, state, content_document_id, content_version, interval_seconds, enabled, expected_revision. Сохраняет правило для working (рабочее время) или non_working (нерабочее). Укажите опубликованную версию неархивированного документа контента этого бота и интервал между автоответами в секундах (от 1 до 2 678 400).

Во всех операциях записи обязателен expected_revision. Используйте 0 только при создании расписания или правила автоответа. Для обновления возьмите текущую revision из ответа чтения. Расписание и его праздники используют общую ревизию, которая меняется при любой записи в них. У каждого правила автоответа для пары scope и state своя ревизия. Если ревизия устарела, прочитайте данные заново и примените изменения к свежей версии.

Эти инструменты управляют работой поддержки. Настройки доступности в самом веб-виджете задаются через get_widget_settings и update_widget_settings.

Статистика и аналитика (stats)

get_support_analytics возвращает отчёт поддержки за выбранный период, get_support_analytics_details – постраничную детализацию метрики с подписанным курсором. Нужны stats:read и право аналитики проекта; период не должен превышать 366 дней.

  • get_stats: stats:read
  • get_stats_summary: stats:read
  • get_stats_recent: stats:read
  • get_stats_log: stats:read
  • get_reaction_health: stats:read
  • get_analytics: stats:read
  • get_analytics_chats: stats:read
  • get_site_widget_analytics: stats:read
  • get_site_popup_analytics: stats:read
  • get_funnel: stats:read

Оба инструмента требуют право проекта «Аналитика» и scope stats:read. Передайте bot_id, from и to; границы периода задаются метками времени RFC 3339. Начало включается, конец исключается: [from, to). Период должен быть положительным и не превышать 366 дней; дни в результате указаны в UTC.

get_site_widget_analytics возвращает количество полученных просмотров страниц сайта, наблюдаемых идентификаторов посетителей за весь период, активных веб-диалогов и входящих сообщений, а также дневную динамику. Просмотры могут включать серверные события, а идентификаторы не обязательно соответствуют уникальным людям. get_site_popup_analytics возвращает показы, видимые показы, взаимодействия и конверсии по поп-апам и по дням. Это количества событий, а не людей. Видимый показ означает, что не менее половины поп-апа находилось на экране две секунды подряд во видимой вкладке, но не доказывает прочтение. Финансовые данные эти инструменты не возвращают.

Показы и конверсии поп-апов

  • get_popup_report (popups:read + subscribers:read) – Метрики одного поп-апа по дням (days).

  • get_site_popup_analytics (stats:read) – Итоги по каждому поп-апу за период и дневные итоги по всем поп-апам (popups, days).

  • measured_shown. Число отдельных показов с корректным impression_id и идентификатором контакта (subscriber_id).

  • converted_impressions. Число таких показов с привязанной конверсией. Каждый показ учитывается не более одного раза.

  • impression_conversion_rate = converted_impressions / measured_shown

  • impression_coverage = measured_shown / shown

Обе доли возвращаются числами от 0 до 1. При нулевом знаменателе значение равно null.

Для привязки конверсии должны совпасть идентификатор показа, проект, поп-ап, вариант и контакт. Конверсия может быть зарегистрирована не раньше чем за 60 секунд до показа и строго раньше чем через 24 часа после него. Она относится к дню показа по UTC.

Исторические события без идентификаторов показов по-прежнему учитываются в shown, viewed, interacted и converted по времени события. Их нельзя связать с измеренным показом. Если за период есть только показы без измерения, доля измеренных показов равна 0, а доля показов с конверсией равна null.

Общие эксперименты (experiments)

  • list_experiments: experiments:read
  • get_experiment: experiments:read
  • get_experiment_report: experiments:read

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

{
  "name": "get_experiment_report",
  "arguments": { "bot_id": "<bot-id>", "experiment_id": "<experiment-id>", "version": 2 }
}

Сохранённые воронки событий пока доступны только по REST. Не путайте устаревший get_funnel выше, который возвращает автоматическую воронку статистики, с сохранённым определением воронки или её когортой. Для этих сценариев используйте ограниченные REST-эндпоинты из руководства по воронкам.

Биллинг: чтение (billing)

  • get_balance: billing:read
  • list_tariffs: billing:read
  • get_transactions: billing:read

В чужом кабинете все три требуют права кабинета billing.read, иначе: permission denied: missing cabinet right.

Отправка сообщений

  • send_message: broadcasts:write: отправка сообщения от имени бота; расход баланса учитывается автоматически по владельцу токена.

Ресурсы

Помимо инструментов сервер отдаёт ресурсы: их можно читать, чтобы не угадывать структуру:

  • mybot://openapi.yaml: полная OpenAPI-спека (та же, что отдаётся по /openapi.yaml).
  • mybot://reference: компактный справочник: список инструментов с их scope и конвенции (базовый адрес, пагинация, формат ошибок, лимиты).
  • mybot://schemas/reaction, mybot://schemas/trigger, mybot://schemas/action, mybot://schemas/flow, mybot://schemas/collection: JSON-схемы конфигов. Самое ценное для корректной генерации реакций (триггер, условия, чаты, действия), сценариев и коллекций.
  • mybot://bots: динамический список ваших ботов (быстрый контекст без вызова инструмента).

Промпты

Готовые сценарии (slash-команды у MCP-клиента):

  • setup_autoresponder: собрать бота-автоответчик (аргументы: бот, тема/набор вопросов).
  • segment_broadcast: рассылка по сегменту меток (аргументы: бот, метки, реакция/текст).
  • diagnose_reaction: разобраться, почему реакция не срабатывает (читает реакцию, reaction-health и порядок).
  • import_from_sambot: провести импорт бандла SamBot и проверить результат.
  • weekly_report: сводка по статистике/аналитике бота за период.

Когда выбирать MCP, а когда REST

  • Пишете интеграцию, синхронизацию, скрипт или собственную панель: берите REST.
  • Подключаете GetMyBot к ИИ-ассистенту или агенту, который умеет MCP: берите /mcp.

И тот, и другой интерфейс работают под одним токеном и подчиняются одним и тем же правам владельца. Если инструмента под задачу не нашлось: соответствующий REST-эндпоинт всегда есть в интерактивном справочнике.

Доступность функций проверяется одинаково в REST и MCP. Copilot, Flow Intelligence, Explainable Replay и Vertical Playbooks работают только в кабинетах, для которых они включены. Через другой интерфейс получить доступ к выключенной функции нельзя.

Инструменты ИИ и сценариев

ФункцияИнструментыОбласти доступа
Managed AIinvoke_managed_ai, get_managed_ai_usagemanaged_ai:invoke, managed_ai:usage:read
Copilotcreate_copilot_proposal, get_copilot_proposal, validate_copilot_proposal, simulate_copilot_proposal, apply_copilot_proposal, reject_copilot_proposalcopilot:use + journey read/edit
Flow Intelligenceget_flow_intelligence_policy, preview/update/reaggregation toolsanalytics:read, journey:edit
Replaylist_execution_traces, get_execution_trace, simulate_execution_trace, capture_regression_fixture, list_regression_fixtures, get_regression_fixture, run_regression_fixture, list_replay_runsjourney:read/edit
Playbookslist_vertical_playbooks, setup/preflight/install/upgrade; KPI остаётся REST-onlytemplate, bot, reaction read/write
Onboardingstart_outcome_onboarding, update_outcome_onboarding, complete_outcome_onboardingbot/template/reaction scopes
Metalist_meta_connections, start_meta_authorization, refresh_meta_assets, asset check/select/attach и disconnectintegration/bot scopes

Операции изменения записываются в журнал действий с указанием MCP и идентификатора персонального токена. OAuth возвращает адрес, который нужно открыть в браузере для авторизации. Адреса возврата и входящие вебхуки не вызываются как инструменты. ИИ-агентам пользователя недоступны ключи провайдеров, маршрутизация и сверка расчётов.

Что дальше

Правила визуального отслеживания

Для list_tracking_rules нужен tracking:read; создание, изменение и удаление требуют tracking:write, права управления реакциями и выполнения требований 2FA. Включённое правило собирает события и указанные значения на подходящих страницах: проверяйте настройки перед включением. Для изменения и удаления передайте актуальную revision из списка как expected_revision; при конфликте перечитайте правило. Неуказанные поля при изменении сохраняются.

  • list_tracking_rules: bot_id
  • create_tracking_rule: bot_id, name, event_name, trigger_kind, selector, page_patterns, extractions, enabled
  • update_tracking_rule: bot_id, rule_id, expected_revision; name, event_name, trigger_kind, selector, page_patterns, extractions, enabled
  • delete_tracking_rule: bot_id, rule_id, expected_revision