Документация / API

Справочник по REST API

Каждый эндпоинт находится под /api/v1 и авторизуется с помощью API-ключа из раздела Консоль → Интеграции. Ключи показываются только один раз и могут быть только для чтения или для чтения/записи; отозванные ключи перестают работать немедленно.

Отправляйте ключ в виде Authorization: Bearer bfk_…. Ошибки возвращаются в формате Problem Details JSON с полем code , по которому можно ветвить логику.

GET/api/v1/meобласть действия: read

К какому рабочему пространству и тарифу относится ключ. Простой способ проверить, работает ли ключ.

curl -H "Authorization: Bearer bfk_…" \
  https://your-domain/api/v1/me

GET/api/v1/bots?page=1&pageSize=50область действия: read

Список ботов рабочего пространства со статусом и версией.

GET/api/v1/bots/{botId}область действия: read

Один бот: статус, часовой пояс, версия, последняя ошибка.

GET/api/v1/bots/{botId}/subscribers?q=&page=1&pageSize=50область действия: read

Аудитория бота с возможностью поиска по имени или имени пользователя.

GET/api/v1/bots/{botId}/logs?level=error&limit=50область действия: read

Недавние журналы выполнения; можно фильтровать по уровню.

GET/api/v1/bots/{botId}/analytics?days=30область действия: read

Объём сообщений, сбои доставки и рост числа подписчиков по дням.

GET/api/v1/bots/{botId}/broadcastsобласть действия: read

История рассылок бота.

GET/api/v1/bots/{botId}/logs/streamобласть действия: read

Живые журналы в виде Server-Sent Events. Записи приходят в виде строк data: с JSON LogEntry; комментарий keepalive каждые 15 секунд; сервер закрывает сессию через 10 минут (нужно переподключиться). EventSource не может отправлять заголовки, поэтому используйте потоковую передачу на основе fetch.

curl -N -H "Authorization: Bearer bfk_…"   https://your-domain/api/v1/bots/{botId}/logs/stream

POST/api/v1/bots/{botId}/broadcastsобласть действия: write

Создаёт и ставит рассылку в очередь за один вызов. Тело запроса: { "name": "…", "text": "…", "segmentId": "…" (необязательно) }. Доставка происходит по тому же дозированному конвейеру, что и рассылки из консоли; действует лимит вашего тарифа.

curl -X POST -H "Authorization: Bearer bfk_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"June promo","text":"20% off until Friday"}' \
  https://your-domain/api/v1/bots/{botId}/broadcasts

Коды состояния и лимиты

401 UNAUTHENTICATED — отсутствует или недействителен ключ.
403 FORBIDDEN — у ключа нет прав на запись.
403 PLAN_LIMIT — достигнута квота рассылок; в сообщении указан предел.
404 NOT_FOUND — неверный id, либо бот принадлежит другому рабочему пространству.
Размер страницы ограничен 100; лимит журналов — 200.

Справочник по REST API

Коды состояния и лимиты

Читать дальше

Версии, идемпотентность и ошибки