#Управление ботами

Зарегистрируйте бота на портале Битрикс24, получайте и обновляйте его данные, восстанавливайте доступ при сбоях авторизации и удаляйте бота, когда он больше не нужен.

Скоуп: imbot | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key

#Зарегистрировать бота

POST /v1/bots

Регистрирует нового бота на портале Битрикс24. Операция идемпотентна по code — повторный вызов с тем же кодом вернёт 409 BOT_ALREADY_EXISTS с данными существующего бота.

#Поля запроса (body)

#Типы ботов

⚠ personal и supervisor — привилегированные типы: они получают все сообщения в чатах, где состоят, даже без @упоминания бота. Используйте их осознанно. Регистрация через POST /v1/bots разрешена и не требует админ-роли на стороне Битрикс24 — ограничение задаётся правами вашего webhook/OAuth-токена.

#Доступные цвета

Используются в параметре color при создании и обновлении бота:

RED, GREEN, MINT, LIGHT_BLUE, DARK_BLUE, PURPLE, AQUA, PINK,
LIME, BROWN, AZURE, KHAKI, SAND, MARENGO, GRAY, GRAPHITE

#Примеры

#curl — личный ключ

curl -X POST https://vibecode.bitrix24.tech/v1/bots \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "support_bot",
    "name": "Техподдержка",
    "type": "bot",
    "eventMode": "fetch",
    "color": "AZURE",
    "workPosition": "Помощник по техническим вопросам"
  }'

#curl — OAuth-приложение

curl -X POST https://vibecode.bitrix24.tech/v1/bots \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "support_bot",
    "name": "Техподдержка",
    "type": "bot",
    "eventMode": "fetch",
    "color": "AZURE",
    "workPosition": "Помощник по техническим вопросам"
  }'

#JavaScript — личный ключ

const res = await fetch('https://vibecode.bitrix24.tech/v1/bots', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    code: 'support_bot',
    name: 'Техподдержка',
    type: 'bot',
    eventMode: 'fetch',
    color: 'AZURE',
    workPosition: 'Помощник по техническим вопросам',
  }),
})

const { success, data } = await res.json()
// `data.botId` зеркалит ответ 409 BOT_ALREADY_EXISTS — один и тот же путь для
// success и conflict. `data.bot.id` оставлен для обратной совместимости.
console.log('Bot ID:', data.botId)

#JavaScript — OAuth-приложение

const res = await fetch('https://vibecode.bitrix24.tech/v1/bots', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    code: 'support_bot',
    name: 'Техподдержка',
    type: 'bot',
    eventMode: 'fetch',
    color: 'AZURE',
    workPosition: 'Помощник по техническим вопросам',
  }),
})

const { success, data } = await res.json()

#Поля ответа

#Пример ответа

{
  "success": true,
  "data": {
    "botId": 42,
    "bot": {
      "id": 42,
      "code": "support_bot",
      "type": "bot",
      "eventMode": "fetch",
      "isHidden": false,
      "isReactionsEnabled": true
    },
    "users": [
      {
        "id": 42,
        "name": "Техподдержка",
        "active": true,
        "bot": true
      }
    ]
  }
}

#Пример ответа при ошибке

409 — бот с таким кодом уже существует:

{
  "success": false,
  "error": {
    "code": "BOT_ALREADY_EXISTS",
    "message": "Bot with this code already exists"
  },
  "data": {
    "botId": 42,
    "code": "support_bot",
    "name": "Техподдержка"
  }
}

В поле data возвращаются botId, code и name уже зарегистрированного бота — это идемпотентный путь восстановления записи в базе Вайбкод после рассинхронизации.

#Ошибки

Полный список общих ошибок API — Ошибки.

#Известные особенности

Тип нельзя изменить: после регистрации type фиксируется. PATCH /v1/bots/:botId не принимает это поле.

Восстановление при рассинхронизации: если бот существует на портале Битрикс24, но отсутствует в базе Вайбкод (после сбоя), повторный POST с тем же code восстановит запись в базе.

Формат body отличается от PATCH: при создании поля передаются плоско (code, name, color). При обновлении — вложенная структура { fields: { properties: { name, color } } }.

Формат аватара. Поле avatar принимает изображение PNG или JPEG в виде base64-строки без префикса data:image/...;base64, — передавайте только сами base64-данные. URL изображения или строка с префиксом data: приводят к ответу 422 BITRIX_ERROR. Размер — до ~50 КБ: при превышении запрос завершается успешно, но аватар не сохраняется и остаётся пустым.

Идемпотентность по code: если бот с таким кодом уже есть и в базе Вайбкод, и на портале Битрикс24, вернётся 409 BOT_ALREADY_EXISTS с data: { botId, code, name } существующего бота. Подходит для перезапуска скриптов и проверки факта регистрации без обработки 200/400 раздельно.

Жизненный цикл бота. Бот существует ровно столько, сколько существует локальное приложение, через которое он зарегистрирован. Удаление приложения с портала удаляет и бота.

Операции с ботом — тем же ключом. Бот привязан к API-ключу, которым зарегистрирован. Получение событий, отправка сообщений и обновление выполняются тем же ключом — запрос с другого ключа вернёт 403 BOT_ACCESS_DENIED. Передать бота на активный ключ того же пользователя — или силами администратора аккаунта — можно через `POST /v1/bots/:botId/transfer`.

Режим webhook требует публичного webhookUrl. При eventMode: "webhook" Битрикс24 отправляет события напрямую на webhookUrl, поэтому адрес должен быть публично достижим. Сервер Black Hole с политикой OWNER_ONLY такой запрос не принимает — подробности и решение в разделе Диагностика проблем.

#Смотрите также

• Диагностика проблем
• События
• Сообщения
• Обновить бота
• Перенос владения ботом
• Бот-платформа
• Лимиты и оптимизация