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

POST /v1/bots

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

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

Типы ботов

⚠ personal и supervisor — привилегированные типы: они получают все сообщения в чатах, где состоят, даже без @упоминания бота. Используйте их осознанно.

Регистрация бота выполняется от лица администратора портала Битрикс24 — независимо от типа. Владельцу ключа без этой роли Битрикс24 отвечает отказом в доступе, даже когда скоуп imbot у ключа есть.

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

Используются в параметре 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 уже зарегистрированного бота — это идемпотентный путь восстановления записи в базе Вайбкод после рассинхронизации. Если бота с этим botId нет в GET /v1/bots вашим ключом, он зарегистрирован другим ключом портала: порядок возврата управления — Восстановление доступа к боту.

Ошибки

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

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

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

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

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

Идемпотентность по code: повторный запрос безопасен, когда бот с таким кодом уже есть и в базе Вайбкод, и на портале Битрикс24. Подходит для перезапуска скриптов и проверки факта регистрации без раздельной обработки успеха и конфликта.

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

Операции с ботом — тем же ключом. Бот привязан к API-ключу, которым зарегистрирован. Получение событий, отправка сообщений и обновление выполняются тем же ключом — запрос с другого ключа вернёт 403 BOT_ACCESS_DENIED. Если рабочим остался другой ключ — Восстановление доступа к боту.

Режим webhook требует публичного webhookUrl. При eventMode: "webhook" Битрикс24 отправляет события напрямую на webhookUrl, поэтому адрес должен быть публично достижим. Если webhookUrl ведёт на сервер Black Hole с личным ключом vibe_api_…, событие принимает только политика доступа PUBLIC — при OWNER_ONLY (по умолчанию), NAMED_USERS, DEPARTMENT, PORTAL и AUTHENTICATED оно до приложения не доходит, и такому серверу подойдёт eventMode: "fetch". Сервер, ключ которого привязан к OAuth-приложению, принимает события при любой политике. Подробности и решения — в разделе Диагностика проблем.

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

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