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

POST /v1/bots

Регистрирует бота на портале Битрикс24. Для новой регистрации нужен личный ключ с входящим вебхуком. Повтор с известным платформе ботом сохраняет его токен. Неоднозначное восстановление и регистрация во время смены адреса возвращают 409 — такой ответ нельзя считать подтверждением работоспособности.

Поля запроса (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-приложение

Только повтор для уже известного платформе бота. Создать новую регистрацию через 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-приложение

Только повтор для уже известного платформе бота. Создать новую регистрацию через 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, только если запись уже известна платформе. Отсутствие бота в GET /v1/bots не доказывает, что на портале нет прежней регистрации. Если известен другой ключ владельца, см. Восстановление доступа к боту.

Ошибки

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

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

Восстановление при рассинхронизации. Если локальной записи нет, ответ Битрикс24 с прежним ID или занятым кодом не доказывает создание нового бота. Вайбкод проверяет принятие нового токена отдельным запросом. При недоказанном происхождении возвращается 409 BOT_REGISTRATION_ORIGIN_UNPROVEN, запись не создаётся. Для новой регистрации используйте уникальный code и личный ключ с входящим вебхуком.

Повтор с ответом 201. Прежний токен сохраняется, если бот был известен платформе до запроса и Битрикс24 вернул ту же регистрацию. После смены адреса повтор с прежней регистрацией не снимает needsReregistration: возвращается 409 BOT_DOMAIN_REREGISTRATION_REQUIRED с data: { botId, code, needsReregistration: true }. Запись сохранена. Ботов Agent и Managed Bot нельзя удалять через Bot API — восстановление выполняется через ресурс владельца, а если оно недоступно, через поддержку.

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

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

OAuth и собственный токен. Без прежней локальной записи OAuth и переданный вызывающим кодом токен не допускаются к регистрации: 409 BOT_REGISTRATION_ORIGIN_UNPROVEN возвращается до обращения к Битрикс24. Для известной записи истёкший legacy OAuth-токен требует отдельного обновления авторизации: эта операция не обновляет его и отвечает 409 BOT_REGISTRATION_CONTEXT_CHANGED.

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

Операции с ботом — тем же ключом. Бот привязан к 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-приложению, принимает события при любой политике. Подробности и решения — в разделе Диагностика проблем. Тело входящего события и его проверка — Событие, доставленное вебхуком.

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

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