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

POST /v1/bots

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

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

Параметр Тип Обяз. По умолч. Описание
code string да — Уникальный код бота (латиница, цифры, подчёркивание)
name string да — Отображаемое имя бота
type string нет bot Тип бота: bot, personal, supervisor, openline. Нельзя изменить после регистрации
eventMode string нет fetch Режим событий: fetch (polling) или webhook (push)
webhookUrl string нет — URL для push-уведомлений (только при eventMode: "webhook")
lastName string нет — Фамилия бота
workPosition string нет — Должность бота (отображается под именем)
color string нет — Цвет аватара: RED, GREEN, MINT, LIGHT_BLUE, DARK_BLUE, PURPLE, AQUA, PINK, LIME, BROWN, AZURE, KHAKI, SAND, MARENGO, GRAY, GRAPHITE
gender string нет — Пол: M или F
avatar string нет — URL изображения для аватара
isHidden boolean нет false Скрыть бота из списка контактов
isReactionsEnabled boolean нет true Разрешить реакции на сообщения бота
backgroundId string нет — Фон чата: azure, mint, steel, slate, teal, cornflower, sky, peach, frost
isSupportOpenline boolean нет false Поддержка открытых линий (только для type: "openline")

#Типы ботов

Тип Описание
bot Стандартный бот — реагирует на @упоминание и личные сообщения
personal AI-ассистент — получает все сообщения без @упоминания. Доступны Message.get и Message.getContext
supervisor Системный наблюдатель — получает все сообщения в чатах, где состоит
openline Бот для открытых линий. Требует isSupportOpenline: true

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

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

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

#Примеры

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

Terminal 
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-приложение

Terminal 
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 — личный ключ

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()
console.log('Bot ID:', data.bot.id)

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

javascript 
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()

#Поля ответа

Поле Тип Описание
bot.id number ID бота на портале Битрикс24
bot.code string Уникальный код бота
bot.type string Тип бота
bot.eventMode string Режим событий: fetch или webhook
bot.isHidden boolean Скрыт из списка контактов
bot.isReactionsEnabled boolean Разрешены реакции
users array Массив пользователей Битрикс24, созданных для бота

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

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

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

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

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

#Ошибки

HTTP Код Описание
400 CODE_REQUIRED Не передан параметр code
400 NAME_REQUIRED Не передан параметр name
409 BOT_ALREADY_EXISTS Бот с таким code уже зарегистрирован. Ответ содержит data с botId
422 BITRIX_ERROR Битрикс24 вернул ошибку при регистрации (текст ошибки в message)
502 REGISTRATION_FAILED Битрикс24 не вернул ID бота
403 SCOPE_DENIED API-ключ не имеет скоупа imbot
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

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

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

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

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

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

Идемпотентность по code: если бот с таким кодом уже есть, вернётся 409 с данными существующего бота. Удобно для перезапуска скриптов.

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