Документация для разработчиков · v1

Данные Botnest — там, где они нужны.

Подключайте CRM, таблицы и аналитику через Public API. Здесь — только действующие внешние методы, их права доступа и правила безопасной интеграции.

Отправить первый запрос OpenAPI 3.1 ↗Руководство по сервису

Ключи и доступ

Базовый адрес запросов: https://botnest.su/public/v1. Передавайте ключ в заголовке Authorization: Bearer <API_KEY>. Ключ привязан к организации: API возвращает только её данные.

Откройте «Настройки → Интеграции»

Создавать и отзывать ключи могут владелец и администратор организации.

Назовите ключ и выберите права

Выдавайте только нужные области доступа. Для каждой внешней системы создавайте отдельный ключ.

Сохраните секрет сразу

Полный ключ показывается один раз. Если он утрачен или раскрыт, отзовите его и создайте новый.

Область	Что разрешает
`bots:read`	Список ботов организации
`subscribers:read`	Чтение профилей подписчиков
`deliveries:read`	Статусы и технические причины доставки
`analytics:read`	Агрегированная аналитика

Public API сейчас работает только на чтение. Управление ботами, рассылками, ключами и подписчиками через этот API не поддерживается.

Первый запрос

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

Терминал · cURL

curl --request GET \
  --url 'https://botnest.su/public/v1/bots' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Accept: application/json'

Ответ · пример структуры

{
  "data": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "Мой бот",
      "telegramUsername": "my_example_bot",
      "status": "active",
      "activatedAt": "2026-09-28T10:00:00.000Z",
      "createdAt": "2026-09-27T10:00:00.000Z"
    }
  ]
}

Проверка без кода

В «Настройки → Интеграции» есть песочница Public API. Она отправляет тестовый запрос с введённым ключом; ключ не сохраняется в настройках.

Доступные методы

Все приведённые ниже запросы используют метод GET. Идентификаторы botId и scenarioId — UUID.

GET/public/v1/botsbots:read

Список ботов организации. Ответ: {"data":[...]}, без пагинации. Поля включают ID, название, Telegram username, статус и даты.

GET/public/v1/subscriberssubscribers:read

Профили подписчиков. Ответ: {"data":[...],"nextCursor":null}. Записи относятся к конкретному боту, поэтому один Telegram-пользователь в разных ботах может встречаться несколько раз.

limit — 1–100, по умолчанию 30; cursor — следующая страница.
botId — конкретный бот; q — поиск (до 120 символов); status — active или blocked.
Выдаются ID, имена и username, Telegram user ID, даты, счётчик сообщений, согласие на маркетинговые сообщения, источник, теги и пользовательские поля. Chat ID и сырые Telegram-обновления не выдаются.

GET/public/v1/deliveriesdeliveries:read

Операционные статусы доставки без текста сообщения, chat ID и Telegram message ID. Ответ содержит data и nextCursor.

limit — 1–100; cursor — следующая страница; botId — фильтр по боту.
status: pending, sent, failed, cancelled.
errorCategory: telegram, network, timeout, storage, configuration, policy, unknown.

GET/public/v1/analytics/overviewanalytics:read

Агрегированные показатели. Параметры: days=7|30|90 (по умолчанию 30), необязательные botId и scenarioId. Ответ содержит объект data.

GET/public/v1/openapi.jsonБез ключа

Машиночитаемый контракт OpenAPI 3.1 для генерации клиента и сверки параметров. Этот метод доступен без авторизации.

Пагинация

Списки подписчиков и доставок возвращают максимум 100 элементов за запрос. Передавайте полученный nextCursor в следующий запрос, пока он не станет null. Не разбирайте курсор вручную: его формат непрозрачен и может измениться.

Следующая страница

GET /public/v1/subscribers?limit=30&cursor=CURSOR_FROM_PREVIOUS_RESPONSE
Authorization: Bearer YOUR_API_KEY

При синхронизации храните идентификаторы записей и учитывайте, что данные могут обновиться между страницами.

Ошибки и лимиты

Ошибки возвращаются в JSON с полем error. Проверяйте HTTP-статус, а не только тело ответа.

Код	Когда возникает	Что делать
`400`	Неверные параметры или курсор (`invalid_query`, `invalid_cursor`)	Проверьте диапазоны, UUID и курсор предыдущей страницы.
`401`	Ключ отсутствует, недействителен, истёк или отозван	Проверьте Bearer-заголовок и создайте новый ключ при необходимости.
`403`	Нет требуемой области доступа	Создайте ключ с нужным scope; текущий ключ не расширяется.
`429`	Превышен лимит запросов	Снизьте частоту и повторите запрос с задержкой.
`5xx`	Временная ошибка сервиса	Повторите с ограниченным экспоненциальным ожиданием.

Лимиты

До 300 запросов в минуту на методы списка; до 120 в минуту на аналитику и OpenAPI-контракт. Не запускайте бесконечные повторы. Значения задаются на сервере и могут меняться с развитием сервиса.

Исходящие Webhook

Webhook отправляют события из Botnest на ваш HTTPS-адрес. Создавайте их в «Настройки → Интеграции», выбирайте события и сохраняйте секрет подписи при создании. Доступны subscriber.created, subscriber.updated, broadcast.completed, broadcast.failed, delivery.failed. В панели можно отправить тестовое событие.

Тело Webhook · пример

{
  "id": "event-id",
  "type": "subscriber.created",
  "createdAt": "2026-09-28T10:00:00.000Z",
  "data": { "subscriberId": "subscriber-id" }
}

Сверяйте X-Botnest-Timestamp и X-Botnest-Signature. Подпись имеет вид v1=HEX_HMAC_SHA256(secret, timestamp + "." + raw_body). Используйте именно исходные байты тела до JSON-разбора, сравнивайте подписи в постоянное время и отклоняйте устаревшие timestamps. Идентификаторы события id и доставки X-Botnest-Delivery помогут избежать повторной обработки.

Ответ 2xx подтверждает доставку. Временные сбои повторяются с задержкой; после исчерпания попыток запись остаётся в журнале доставки Webhook.

Не путайте направления

Public API — это запросы из вашей системы в Botnest. Исходящий Webhook — это события из Botnest в вашу систему. Telegram Webhook вашего бота настраивается сервисом отдельно.

Безопасность интеграции

Храните ключи и Webhook-секреты на сервере или в менеджере секретов; не добавляйте их в JavaScript браузера и репозиторий.
Используйте HTTPS. На утечку реагируйте отзывом API-ключа или ротацией Webhook-секрета в панели.
Не выгружайте больше персональных данных, чем требуется задаче. Учитывайте согласия и правила обработки данных вашей аудитории.
Создавайте отдельный ключ для теста и боевой интеграции, ограничивайте права и отслеживайте последнее использование в панели.

Контракт и помощь

Точный набор полей и типов опубликован в OpenAPI 3.1. В панели «Интеграции» можно скачать контракт, проверить запрос в песочнице и получить пакеты для n8n или Make.

Руководство по Botnest

Сценарии, подписчики, рассылки и магазин.

Открыть →

Настройки интеграций

Управление ключами, Webhook и тестовыми запросами — после входа в сервис.

Перейти →