REST API и токены

Кроме визуального конструктора, GetMyBot открыт программно: данными бота можно управлять по REST API. Есть два вида токенов: для доступа к конкретному боту и персональные (для автоматизации и интеграций уровня аккаунта).

API-токены бота

Создаются в Настройки → API-токены. Каждый токен привязан к боту и позволяет обращаться к его REST-эндпоинтам (реакции, пользователи, коллекции, статистика и т. д.). Токен показывается только один раз при создании: сохраните его в надёжном месте; список показывает имя, маску и дату создания. Лишние токены удаляйте.

Персональные токены доступа (PAT)

Персональные токены доступа (PAT, начинаются с mbp_) работают на уровне аккаунта и используются для автоматизации и интеграций. Создаются в личном кабинете; передаются в заголовке Authorization: Bearer mbp_…. У токена есть области доступа (scopes): набор разрешений вида ресурс:действие (например, reactions:read, bots:write), а * означает полный доступ. Срок действия ограничивается, а сами токены хранятся в хешированном виде. Это удобный способ дать скрипту ограниченный доступ без выдачи пароля.

Что доступно по API

Через API доступны те же сущности, что и в интерфейсе: боты и их настройки, реакции (включая импорт/экспорт), подписчики и метки, коллекции и записи, статистика и журнал запросов, рассылки. Это позволяет строить собственные панели, синхронизации и автоматизации поверх GetMyBot.

Каналы и WhatsApp

GetMyBot мультиканален (Telegram + WhatsApp + VK), и каналы бота тоже управляются по REST. Каналы и WhatsApp-шаблоны гейтятся общими scope bots:read / bots:write: отдельного channel-scope нет.

• GET /api/channels/capabilities (bots:read): матрица возможностей каналов (веб-сессия работает без scope).
• GET /api/bots/{botID}/channels (bots:read): список каналов бота.
• POST /api/bots/{botID}/channels (bots:write): подключить канал WhatsApp или VK.
• DELETE /api/bots/{botID}/channels/{channelID} (bots:write): отключить канал.
• GET /api/bots/{botID}/channels/{channelID}/templates (bots:read): каталог WhatsApp-шаблонов канала.
• POST /api/bots/{botID}/channels/{channelID}/templates (bots:write): создать шаблон и отправить на модерацию Meta.
• POST /api/bots/{botID}/channels/{channelID}/templates/sync (bots:write): пересинхронизировать каталог из Meta.
• PUT /api/bots/{botID}/channels/{channelID}/templates/{templateID} (bots:write): изменить шаблон.
• DELETE /api/bots/{botID}/channels/{channelID}/templates/{templateID} (bots:write): удалить шаблон.
• POST /api/bots/{botID}/channels/{channelID}/templates/media (bots:write): загрузить медиа-пример заголовка (изображение/видео/документ).

Схемы запросов и ответов, параметры и примеры: в Справочнике API. Пользовательское описание канала и шаблонов: на странице WhatsApp.

CRM-подключения

У CRM своя пара скоупов, crm:read / crm:write, отдельная от integrations:*: креды CRM арендатора и её операции синхронизации гораздо чувствительнее подключения к Sheets. Каждый маршрут дополнительно проверяет право бота «Реакции».

Подключение зависит от провайдера:

• POST /api/bots/{botID}/crm/connections/amocrm/start (crm:write) - отправьте {"account_key": "acme.amocrm.ru"} и получите redirect_url, который нужно открыть в браузере. Запусков не больше трёх в минуту на аккаунт; пока на платформе не настроено OAuth-приложение amoCRM, эндпоинт отвечает 503. Bitrix24 отвечает 503 по той же причине.
• GET /api/integrations/crm/{provider}/callback: цель браузерного редиректа. Токен не нужен: аутентификацией служит одноразовое состояние на 5 минут, выданное при запуске. В ответ отдаётся безопасная сводка подключения, но никогда не его креды.
• POST /api/bots/{botID}/crm/connections/retailcrm (crm:write): подключение по API-ключу.
• POST /api/bots/{botID}/crm/connections/ozmacrm (crm:write): подключение по OIDC-кредам, логину и конфигурации сущностей.

Кроме подключения есть маршруты обнаружения полей, воронок, ревизий маппинга, предпросмотра, первичной синхронизации, повторной сверки, операций и задач, разбора конфликтов, а также DELETE /api/bots/{botID}/crm/connections/{connectionID} для отключения. Ещё три действия по подписчику (статус CRM, ручная синхронизация, выгрузка переписки) живут под /api/bots/{botID}/subscribers/{subscriberID}/crm/… со скоупами subscribers:* и правом «Диалоги».

Шесть инструментов MCP только для чтения повторяют чтения CRM: см. MCP. Полная таблица маршрутов, скоупы и поведение провайдеров - на странице CRM-интеграции.

Контент, email-рассылки и поп-апы

У контентного направления собственные скоупы. Эндпоинты контента, рассылок и поп-апов дополнительно проверяют право «Реакции» на уровне бота, поэтому токен не дотянется дальше своего аккаунта.

• content:read / content:write: документы и шаблоны контента: GET|POST /api/bots/{botID}/content, GET /api/bots/{botID}/content/{documentID}, PATCH /api/bots/{botID}/content/{documentID}/draft, POST /api/bots/{botID}/content/{documentID}/publish|clone|archive|test-send, POST /api/bots/{botID}/content/{documentID}/validate|preview, GET /api/bots/{botID}/content/test-recipients, GET|POST /api/bots/{botID}/content-templates, DELETE /api/bots/{botID}/content-templates/{templateID}.
• email_campaigns:read / email_campaigns:write: рассылки и их отчёты: GET|POST /api/bots/{botID}/email-campaigns, GET|PATCH /api/bots/{botID}/email-campaigns/{campaignID}, GET /api/bots/{botID}/email-campaigns/{campaignID}/report|recipients|links, POST /api/bots/{botID}/email-campaigns/{campaignID}/consent-preview, POST /api/bots/{botID}/email-campaigns/{campaignID}/test-send|schedule|clone|pause|resume|cancel|archive.
• popups:read / popups:write: GET|POST /api/bots/{botID}/popups, PATCH|DELETE /api/bots/{botID}/popups/{popupID}, GET /api/bots/{botID}/popups/{popupID}/stats|experiment, POST /api/bots/{botID}/popups/preflight.
• settings:read / settings:write: домены отправки и входящие почтовые маршруты в /api/bots/{botID}/email/…. Домен отправки это настройка бота, поэтому он остался на скоупе настроек, а не получил отдельный. Для чтения достаточно доступа к боту; создание, проверка и удаление требуют ещё и права «Реакции».

Обратите внимание: consent-preview, validate и preview отправляются методом POST, хотя ничего не меняют, и попадают в аудит как любой другой аутентифицированный POST.

Изменения используют оптимистичную блокировку. Передавайте expected_revision, который вы прочитали, и считайте 409 сигналом «перезагрузи и повтори», а не ошибкой транспорта. Запрос POST /api/bots/{botID}/email-campaigns/{campaignID}/schedule дополнительно требует "confirm": true и отвечает 422 с полной проверкой получателей, если рассылка не готова.

Публичные эндпоинты трекинга, отписки и вебхуков провайдера (/e/t/…, /u/…, /esp/{provider}/webhook, /esp/{provider}/inbound) не относятся к API по токену. Они описаны в статье Email-рассылки.

Браузерный пуш и клиентский SDK

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

Пуш в браузере: web_push:read / web_push:write:

• GET /api/bots/{botID}/web-push (web_push:read): очищенная конфигурация: публичный ключ VAPID, контакт, разрешённые origin для переходов и тихие часы. Приватный ключ не возвращается никогда.
• GET /api/bots/{botID}/web-push/subscriptions (web_push:read): недавние подписки со статусом согласия, семейством браузера, локалью и часовым поясом. Адрес пуш-сервиса и ключи шифрования не сериализуются никогда.
• GET /api/bots/{botID}/web-push/report (web_push:read): счётчики подписок и квитанций.
• POST /api/bots/{botID}/web-push/enable (web_push:write): при первом вызове создаёт пару ключей VAPID, дальше работает как идемпотентное обновление настроек.
• PATCH /api/bots/{botID}/web-push (web_push:write): контакт, origin для переходов, тихие часы, признак включённости.
• POST /api/bots/{botID}/web-push/rotate-keys (web_push:write): отвечает 409 с числом активных подписок, пока не передан "confirm": true; подтверждение гасит все существующие подписки.
• POST /api/bots/{botID}/web-push/test (web_push:write): единственная существующая отправка: одно сообщение в одну подписку со ссылкой на опубликованный документ типа Push.

Клиентский SDK: customer_sdk:read / customer_sdk:write:

• GET /api/bots/{botID}/customer-sdk (customer_sdk:read): очищенный проект: ключ проекта, регион, списки разрешённых приложений, версия секрета личности и, во время ротации, момент истечения предыдущего секрета.
• GET /api/bots/{botID}/customer-sdk/installations (customer_sdk:read): до 200 недавних установок.
• GET /api/bots/{botID}/customer-sdk/report (customer_sdk:read): счётчики установок и пуш-токенов.
• POST /api/bots/{botID}/customer-sdk/enable (customer_sdk:write): создаёт проект и один раз возвращает секрет личности, дальше работает как идемпотентное обновление настроек. На развёртывании без настроенного секрета подписи ключей проекта отвечает 503.
• PATCH /api/bots/{botID}/customer-sdk (customer_sdk:write): списки разрешённых приложений и признак включённости.
• POST /api/bots/{botID}/customer-sdk/rotate-secret (customer_sdk:write) - возвращает новый секрет личности и оставляет предыдущий рабочим ещё сутки.
• DELETE /api/bots/{botID}/customer-sdk/installations/{installationID} (customer_sdk:write): отзывает одно устройство.

Клиентская поверхность самого SDK, /sdk/v1/*, в это API не входит. Она авторизуется токеном установки и эпохой личности и намеренно не принимает личные токены: ровно так же, как /api/* не принимает токен установки. Она описана отдельным документом OpenAPI, который сервер публикует без авторизации по адресу GET /sdk/openapi.yaml.

Рассылки

У рассылок всего один скоуп: broadcasts:write. Пары read/write, как у контента, email-рассылок и поп-апов, здесь нет, поэтому чтение тоже требует broadcasts:write: и список, и отчёт, и постраничные получатели. Токен только на чтение рассылок выдать нельзя. Все маршруты дополнительно проверяют право бота «Реакции».

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

• GET /api/bots/{botID}/broadcasts: список; ?archived=true добавляет архивные.
• POST /api/bots/{botID}/broadcasts: создать черновик.
• PATCH /api/bots/{botID}/broadcasts/{broadcastID}: изменить черновик.
• POST /api/bots/{botID}/broadcasts/{broadcastID}/preflight: проверка получателей; ничего не отправляет, но это POST и он попадает в аудит.
• POST /api/bots/{botID}/broadcasts/{broadcastID}/schedule: запуск.
• POST /api/bots/{botID}/broadcasts/{broadcastID}/test-send: тест на один подтверждённый контакт.
• POST /api/bots/{botID}/broadcasts/{broadcastID}/archive: в архив.
• GET /api/bots/{botID}/broadcasts/{broadcastID}/report: отчёт по каналам.
• GET /api/bots/{botID}/broadcasts/{broadcastID}/recipients: получатели, параметры limit и cursor.

Старые рассылки по реакции никуда не делись и живут на том же базовом пути. Запускаются они отдельным маршрутом POST /api/bots/{botID}/reactions/{reactionID}/broadcast с телом {"paid": false, "labels": ["vip"]}: это единственное место, где рассылку можно сузить по меткам. Четыре маршрута общие для обеих систем:

• GET /api/bots/{botID}/broadcasts/{broadcastID},
• POST /api/bots/{botID}/broadcasts/{broadcastID}/pause|resume|cancel.

Обработчик сначала пробует найти рассылку второго поколения и только потом падает обратно на старую строку, поэтому тело и ответ зависят от того, чей это идентификатор. Рассылке второго поколения нужен {"expected_revision": N}, и она возвращает саму рассылку целиком; старая тело игнорирует и отвечает {"status": "pausing"}, {"status": "resuming"} или {"status": "canceled"}.

Тела запросов строгие: неизвестное поле: это 400, а не молча проигнорированный ключ. Изменения используют оптимистичную блокировку: передавайте прочитанный expected_revision, а 409 считайте сигналом «перезагрузи и повтори». schedule дополнительно требует "confirm": true - без него ответ 400.

Что означают коды ответа рассылок:

• 402: в тарифе владельца бота нет функции рассылок;
• 403: платные рассылки для этого бота не включены;
• 409: ревизия устарела, либо рассылка не готова к запуску (не опубликованный контент, непересчитанный сегмент, незапущенный эксперимент, пустая аудитория);
• 422: контента нет либо он не проходит валидацию для одного из каналов;
• 429: слишком частые тестовые отправки.

В MCP тот же скоуп покрывает start_broadcast, get_broadcast, pause_broadcast, resume_broadcast, cancel_broadcast, list_content_broadcasts и get_content_broadcast_report. Два последних и get_broadcast только читают, но broadcasts:write им всё равно нужен - скоупа на чтение просто нет. Создание черновика, его правка, проверка получателей, запуск, тестовая отправка и архивирование рассылки второго поколения через MCP не публикуются, только по REST; pause_broadcast, resume_broadcast и cancel_broadcast работают лишь со старыми рассылками по реакции. Пользовательское описание обоих потоков: на странице Рассылки.

Мобильный доступ

У платформы есть мобильное приложение со своей авторизацией (access- и refresh-токены) и сводным дашбордом по ботам: оно использует тот же бэкенд.

Справочник API

Полный интерактивный справочник по публичному API доступен на странице Справочник API: там перечислены все доступные по PAT эндпоинты, параметры, схемы запросов и ответов, требуемые scopes и готовые примеры запросов (curl, JavaScript, Python). Прямо со страницы можно выполнить пробный запрос со своим токеном.

Воронки и эксперименты

Определения и отчёты сохранённых воронок используют analytics:read и analytics:write; для сохранения когорты как сегмента также нужен segments:write. Определения экспериментов, операции жизненного цикла, отчёты и когорты используют experiments:read и experiments:write. Все эти эндпоинты дополнительно проверяют право бота «Аналитика». Логирование аудита зависит от HTTP-метода: для аутентифицированного владельца фиксируется каждый POST, PUT, PATCH и DELETE, включая семантически read-only запросы отчёта, query и когорты, отправленные через POST. Чтение и списки через GET не становятся событиями аудита.

Для отчётов всегда передавайте ограниченный диапазон RFC3339 в UTC. Воронки и эксперименты ограничены 366 днями. Доход эксперимента содержит целое поле minor и валюту ISO 4217 currency; не считайте смешанный валютный итог на клиенте.

curl "$BASE_URL/api/bots/$BOT_ID/funnels?limit=50&cursor=$CURSOR" \
  -H "Authorization: Bearer $PAT"

Верните серверу курсор next без изменений. Неверный курсор или тело запроса вернёт 400, а недоступный в боте ресурс или явно запрошенная версия эксперимента: 404. Устаревшая ревизия мутации или конфликт выбора победителя вернёт 409. Полные тела запросов и схемы ответов есть в Справочнике API и руководствах Воронки и Эксперименты.

• Сохранённые воронки событий: семантика и запросы когорты.
• Эксперименты и атрибуция: версии, факты и доход.

Безопасность

• Токены показываются один раз; храните их как секреты.
• Секреты ботов и учётных данных хранятся в зашифрованном виде.
• Аудит зависит от метода: фиксируются аутентифицированные POST, PUT, PATCH и DELETE; чтение через GET не фиксируется.

Customer AI, аналитика сценариев, playbooks и Meta

Публичный API покрывает полный агентный workflow:

• Managed AI: POST /api/v1/ai/responses (managed_ai:invoke) и GET /api/v1/ai/usage (managed_ai:usage:read). Profiles: fast, balanced, quality; provider: auto, openai, anthropic, deepseek. Для вызова обязателен Idempotency-Key; переход с tenant key на платный Managed AI никогда не происходит молча.
• Copilot: proposal создаётся в /api/reactions/{rootID}/copilot/proposals, затем его можно получить, проверить, симулировать, применить или отклонить через /api/copilot/proposals/{proposalID}. Apply создаёт draft, но не публикует его.
• Flow Intelligence: overlay/samples у реакции, policy и bounded reaggregation в /api/bots/{botID}/flow-intelligence/*.
• Explainable Replay: traces, детерминированная simulation, redacted regression fixtures и runs. Reveal защищённого artifact не публикуется для агента.
• Vertical Playbooks: /api/playbooks/catalog, resumable setup/preflight/install/upgrade и KPI.
• Outcome onboarding: POST|PATCH /api/onboarding/session и POST /api/onboarding/session/complete.
• Messenger и Instagram: /api/meta/connections возвращает OAuth browser handoff, после чего принадлежащие кабинету assets можно проверить, выбрать и привязать. Tokens не возвращаются.

Provider keyring, routing, prices и reconciliation доступны только superadmin и намеренно не входят в customer API/MCP.

Copilot, Flow Intelligence, Explainable Replay и Vertical Playbooks дополнительно проверяют rollout кабинета. Выключенная или не назначенная фича закрывается fail-closed и не может быть обойдена через MCP.

Что дальше

• Справочник API: интерактивный список эндпоинтов и примеры.
• Настройки, команда и доступ: создание API-токенов бота.
• Коллекции и данные: данные, доступные по API.
• Веб-запросы и вебхуки: интеграции в обе стороны.