База знаний GetMyBot

REST API и токены

Как управлять ботами из своей программы. Виды ключей доступа, операции REST API и ссылки на примеры запросов.

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

REST API позволяет вашей программе обращаться к GetMyBot по HTTP: например, читать заявки из коллекции, создавать реакции или получать статистику. Если вы настраиваете бота только в кабинете, API не требуется. Для интеграции начните с первого запроса, а точные поля смотрите в интерактивном справочнике.

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

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

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

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

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

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

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

Каналы и WhatsApp

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

  • 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 и её синхронизации выделен отдельно. Каждый маршрут также проверяет право бота «Реакции».

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

  • 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 сохранены на английском; рядом указано, какую задачу они решают:

  • Managed AI: POST /api/v1/ai/responses (managed_ai:invoke) и GET /api/v1/ai/usage (managed_ai:usage:read): запрос к ИИ и чтение расхода. Профили: fast, balanced, quality; провайдер: auto, openai, anthropic, deepseek. Для вызова обязателен Idempotency-Key. Использование вашего ключа провайдера не переключается автоматически на платный Managed AI.
  • Copilot: создаёт предложение изменения реакции в /api/reactions/{rootID}/copilot/proposals. Через /api/copilot/proposals/{proposalID} его можно прочитать, проверить, пробно выполнить, применить или отклонить. Применение создаёт черновик и не публикует его.
  • Flow Intelligence: показывает данные о прохождении реакции, примеры запусков и правила анализа. Настройки и пересчёт за ограниченный период доступны в /api/bots/{botID}/flow-intelligence/*.
  • Explainable Replay: позволяет прочитать журнал выполнения и воспроизвести его, подготовить тестовый пример с удалёнными чувствительными данными и проверить повторный запуск. Раскрытие защищённых материалов агенту недоступно.
  • Vertical Playbooks: каталог готовых сценариев /api/playbooks/catalog, продолжение прерванной настройки, проверка готовности, установка, обновление и показатели результата (KPI).
  • Outcome onboarding: пошаговая начальная настройка под задачу. Адреса: POST|PATCH /api/onboarding/session и POST /api/onboarding/session/complete.
  • Messenger и Instagram: /api/meta/connections возвращает адрес для авторизации Meta в браузере. Затем можно проверить, выбрать и подключить страницы и аккаунты вашего кабинета. Секретные токены в ответ не возвращаются.

Ключи провайдеров, маршрутизация, цены и сверка расчётов доступны только суперадминистратору. Через пользовательские API и MCP управлять ими нельзя.

Copilot, Flow Intelligence, Explainable Replay и Vertical Playbooks должны быть включены для вашего кабинета. Если функция выключена или ещё не предоставлена кабинету, запрос будет отклонён. MCP использует то же ограничение.

Что дальше