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

`POST /v1/bots`

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

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

| Параметр | Тип | Обяз. | По умолч. | Описание |
|----------|-----|:-----:|-----------|---------|
| `code` | string | да | — | Уникальный код бота (латиница, цифры, подчёркивание) |
| `name` | string | да | — | Отображаемое имя бота |
| `type` | string | нет | `bot` | [Тип бота](#типы-ботов): `bot`, `personal`, `supervisor`, `openline`. Нельзя изменить после регистрации. От типа зависит доступ к [чтению сообщений](/docs/bots/messages) |
| `eventMode` | string | нет | `fetch` | Режим событий: `fetch` (опрос) или `webhook` (доставка на ваш адрес) |
| `webhookUrl` | string | нет | — | URL для доставки событий (только при `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 | нет | — | Аватар бота: PNG или JPEG как base64-строка без префикса `data:image/...;base64,`, до ~50 КБ. См. «Формат аватара» в «Известных особенностях» |
| `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-ассистент — получает все сообщения без @упоминания. Доступны [`GET /v1/bots/:botId/messages/:messageId`](/docs/bots/messages/get) и [`GET /v1/bots/:botId/messages/:messageId/context`](/docs/bots/messages/context) |
| `supervisor` | Системный наблюдатель — получает все сообщения в чатах, где состоит |
| `openline` | Бот для открытых линий. Требует `isSupportOpenline: true` |

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

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

```bash
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()
// `data.botId` зеркалит ответ 409 BOT_ALREADY_EXISTS — один и тот же путь для
// success и conflict. `data.bot.id` оставлен для обратной совместимости.
console.log('Bot ID:', data.botId)
```

### 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()
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `botId` | number | ID бота на портале Битрикс24. Зеркалит `data.botId` из 409-ответа — один и тот же путь при успехе и при конфликте |
| `bot.id` | number | Дубликат `botId` для обратной совместимости. ID бота на портале Битрикс24 |
| `bot.code` | string | Уникальный код бота |
| `bot.type` | string | Тип бота |
| `bot.eventMode` | string | Режим событий: `fetch` или `webhook` |
| `bot.isHidden` | boolean | Скрыт из списка контактов |
| `bot.isReactionsEnabled` | boolean | Разрешены реакции |
| `users` | array | Массив пользователей Битрикс24, созданных для бота |
| `users[].id` | number | Идентификатор пользователя-бота на портале. Совпадает с `botId` |
| `users[].name` | string | Отображаемое имя бота — то, что видят участники чата |
| `users[].workPosition` | string | Должность под именем бота |
| `users[].active` | boolean | Активен ли пользователь-бот |
| `users[].bot` | boolean | Признак бота, всегда `true` |

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

```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 — бот с таким кодом уже существует:

```json
{
  "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` вашим ключом, он зарегистрирован другим ключом портала: порядок возврата управления — [Восстановление доступа к боту](/docs/bots/ownership-recovery).

## Ошибки

| 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` |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ в режиме «только чтение» |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

**Восстановление при рассинхронизации:** если бот существует на портале Битрикс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`. Если рабочим остался другой ключ — [Восстановление доступа к боту](/docs/bots/ownership-recovery).

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

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

- [Диагностика проблем](/docs/bots/troubleshooting)
- [События](/docs/bots/events)
- [Сообщения](/docs/bots/messages)
- [Обновить бота](/docs/bots/management/update)
- [Перенос владения ботом](/docs/bots/management/transfer)
- [Восстановление доступа к боту](/docs/bots/ownership-recovery)
- [Бот-платформа](/docs/bots)
- [Лимиты и оптимизация](/docs/optimization)