[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-bots\u002Fmanagement\u002Fcreate":3,"docs-tabs-bots\u002Fmanagement\u002Fcreate":6},{"content":4,"lastmod":5},"\n## Зарегистрировать бота\n\n`POST \u002Fv1\u002Fbots`\n\nРегистрирует нового бота на портале Битрикс24. Операция идемпотентна по `code` — повторный вызов с тем же кодом вернёт `409 BOT_ALREADY_EXISTS` с данными существующего бота.\n\n## Поля запроса (body)\n\n| Параметр | Тип | Обяз. | По умолч. | Описание |\n|----------|-----|:-----:|-----------|---------|\n| `code` | string | да | — | Уникальный код бота (латиница, цифры, подчёркивание) |\n| `name` | string | да | — | Отображаемое имя бота |\n| `type` | string | нет | `bot` | [Тип бота](#типы-ботов): `bot`, `personal`, `supervisor`, `openline`. Нельзя изменить после регистрации |\n| `eventMode` | string | нет | `fetch` | Режим событий: `fetch` (polling) или `webhook` (push) |\n| `webhookUrl` | string | нет | — | URL для push-уведомлений (только при `eventMode: \"webhook\"`) |\n| `lastName` | string | нет | — | Фамилия бота |\n| `workPosition` | string | нет | — | Должность бота (отображается под именем) |\n| `color` | string | нет | — | Цвет аватара: `RED`, `GREEN`, `MINT`, `LIGHT_BLUE`, `DARK_BLUE`, `PURPLE`, `AQUA`, `PINK`, `LIME`, `BROWN`, `AZURE`, `KHAKI`, `SAND`, `MARENGO`, `GRAY`, `GRAPHITE` |\n| `gender` | string | нет | — | Пол: `M` или `F` |\n| `avatar` | string | нет | — | Аватар бота: PNG или JPEG как base64-строка без префикса `data:image\u002F...;base64,`, до ~50 КБ. См. «Формат аватара» в «Известных особенностях» |\n| `isHidden` | boolean | нет | `false` | Скрыть бота из списка контактов |\n| `isReactionsEnabled` | boolean | нет | `true` | Разрешить реакции на сообщения бота |\n| `backgroundId` | string | нет | — | Фон чата: `azure`, `mint`, `steel`, `slate`, `teal`, `cornflower`, `sky`, `peach`, `frost` |\n| `isSupportOpenline` | boolean | нет | `false` | Поддержка открытых линий (только для `type: \"openline\"`) |\n\n## Типы ботов\n\n| Тип | Описание |\n|-----|---------|\n| `bot` | Стандартный бот — реагирует на @упоминание и личные сообщения |\n| `personal` | AI-ассистент — получает все сообщения без @упоминания. Доступны `Message.get` и `Message.getContext` |\n| `supervisor` | Системный наблюдатель — получает все сообщения в чатах, где состоит |\n| `openline` | Бот для открытых линий. Требует `isSupportOpenline: true` |\n\n> ⚠ **`personal` и `supervisor` — привилегированные типы:** они получают все сообщения в чатах, где состоят, даже без @упоминания бота. Используйте их осознанно. Регистрация через `POST \u002Fv1\u002Fbots` разрешена и не требует админ-роли на стороне Битрикс24 — ограничение задаётся правами вашего webhook\u002FOAuth-токена.\n\n## Доступные цвета\n\nИспользуются в параметре `color` при создании и обновлении бота:\n\n```\nRED, GREEN, MINT, LIGHT_BLUE, DARK_BLUE, PURPLE, AQUA, PINK,\nLIME, BROWN, AZURE, KHAKI, SAND, MARENGO, GRAY, GRAPHITE\n```\n\n## Примеры\n\n### curl — личный ключ\n\n```bash\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fbots \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"code\": \"support_bot\",\n    \"name\": \"Техподдержка\",\n    \"type\": \"bot\",\n    \"eventMode\": \"fetch\",\n    \"color\": \"AZURE\",\n    \"workPosition\": \"Помощник по техническим вопросам\"\n  }'\n```\n\n### curl — OAuth-приложение\n\n```bash\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fbots \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"code\": \"support_bot\",\n    \"name\": \"Техподдержка\",\n    \"type\": \"bot\",\n    \"eventMode\": \"fetch\",\n    \"color\": \"AZURE\",\n    \"workPosition\": \"Помощник по техническим вопросам\"\n  }'\n```\n\n### JavaScript — личный ключ\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fbots', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    code: 'support_bot',\n    name: 'Техподдержка',\n    type: 'bot',\n    eventMode: 'fetch',\n    color: 'AZURE',\n    workPosition: 'Помощник по техническим вопросам',\n  }),\n})\n\nconst { success, data } = await res.json()\n\u002F\u002F `data.botId` зеркалит ответ 409 BOT_ALREADY_EXISTS — один и тот же путь для\n\u002F\u002F success и conflict. `data.bot.id` оставлен для обратной совместимости.\nconsole.log('Bot ID:', data.botId)\n```\n\n### JavaScript — OAuth-приложение\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fbots', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({\n    code: 'support_bot',\n    name: 'Техподдержка',\n    type: 'bot',\n    eventMode: 'fetch',\n    color: 'AZURE',\n    workPosition: 'Помощник по техническим вопросам',\n  }),\n})\n\nconst { success, data } = await res.json()\n```\n\n## Поля ответа\n\n| Поле | Тип | Описание |\n|------|-----|---------|\n| `botId` | number | ID бота на портале Битрикс24. Зеркалит `data.botId` из 409-ответа — один и тот же путь для success и conflict |\n| `bot.id` | number | Дубликат `botId` для обратной совместимости. ID бота на портале Битрикс24 |\n| `bot.code` | string | Уникальный код бота |\n| `bot.type` | string | Тип бота |\n| `bot.eventMode` | string | Режим событий: `fetch` или `webhook` |\n| `bot.isHidden` | boolean | Скрыт из списка контактов |\n| `bot.isReactionsEnabled` | boolean | Разрешены реакции |\n| `users` | array | Массив пользователей Битрикс24, созданных для бота |\n\n## Пример ответа\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"botId\": 42,\n    \"bot\": {\n      \"id\": 42,\n      \"code\": \"support_bot\",\n      \"type\": \"bot\",\n      \"eventMode\": \"fetch\",\n      \"isHidden\": false,\n      \"isReactionsEnabled\": true\n    },\n    \"users\": [\n      {\n        \"id\": 42,\n        \"name\": \"Техподдержка\",\n        \"active\": true,\n        \"bot\": true\n      }\n    ]\n  }\n}\n```\n\n## Пример ответа при ошибке\n\n409 — бот с таким кодом уже существует:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BOT_ALREADY_EXISTS\",\n    \"message\": \"Bot with this code already exists\"\n  },\n  \"data\": {\n    \"botId\": 42,\n    \"code\": \"support_bot\",\n    \"name\": \"Техподдержка\"\n  }\n}\n```\n\nВ поле `data` возвращаются `botId`, `code` и `name` уже зарегистрированного бота — это идемпотентный путь восстановления записи в базе Вайбкод после рассинхронизации.\n\n## Ошибки\n\n| HTTP | Код | Описание |\n|------|-----|---------|\n| 400 | `CODE_REQUIRED` | Не передан параметр `code` |\n| 400 | `NAME_REQUIRED` | Не передан параметр `name` |\n| 409 | `BOT_ALREADY_EXISTS` | Бот с таким `code` уже зарегистрирован. Ответ содержит `data` с `botId` |\n| 422 | `BITRIX_ERROR` | Битрикс24 вернул ошибку при регистрации (текст ошибки в `message`) |\n| 502 | `REGISTRATION_FAILED` | Битрикс24 не вернул ID бота |\n| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `imbot` |\n| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n## Известные особенности\n\n**Тип нельзя изменить:** после регистрации `type` фиксируется. `PATCH \u002Fv1\u002Fbots\u002F:botId` не принимает это поле.\n\n**Восстановление при рассинхронизации:** если бот существует на портале Битрикс24, но отсутствует в базе Вайбкод (после сбоя), повторный `POST` с тем же `code` восстановит запись в базе.\n\n**Формат body отличается от PATCH:** при создании поля передаются плоско (`code`, `name`, `color`). При обновлении — вложенная структура `{ fields: { properties: { name, color } } }`.\n\n**Формат аватара.** Поле `avatar` принимает изображение PNG или JPEG в виде base64-строки **без** префикса `data:image\u002F...;base64,` — передавайте только сами base64-данные. URL изображения или строка с префиксом `data:` приводят к ответу `422 BITRIX_ERROR`. Размер — до ~50 КБ: при превышении запрос завершается успешно, но аватар не сохраняется и остаётся пустым.\n\n**Идемпотентность по code:** если бот с таким кодом уже есть и в базе Вайбкод, и на портале Битрикс24, вернётся `409 BOT_ALREADY_EXISTS` с `data: { botId, code, name }` существующего бота. Подходит для перезапуска скриптов и проверки факта регистрации без обработки 200\u002F400 раздельно.\n\n**Жизненный цикл бота.** Бот существует ровно столько, сколько существует локальное приложение, через которое он зарегистрирован. Удаление приложения с портала удаляет и бота.\n\n**Операции с ботом — тем же ключом.** Бот привязан к API-ключу, которым зарегистрирован. Получение событий, отправка сообщений и обновление выполняются тем же ключом — запрос с другого ключа вернёт `403 BOT_ACCESS_DENIED`. Передать бота на активный ключ того же пользователя — или силами администратора аккаунта — можно через [`POST \u002Fv1\u002Fbots\u002F:botId\u002Ftransfer`](\u002Fdocs\u002Fbots\u002Fmanagement\u002Ftransfer).\n\n**Режим `webhook` требует публичного `webhookUrl`.** При `eventMode: \"webhook\"` Битрикс24 отправляет события напрямую на `webhookUrl`, поэтому адрес должен быть публично достижим. Сервер Black Hole с политикой `OWNER_ONLY` такой запрос не принимает — подробности и решение в разделе [Диагностика проблем](\u002Fdocs\u002Fbots\u002Ftroubleshooting).\n\n## Смотрите также\n\n- [Диагностика проблем](\u002Fdocs\u002Fbots\u002Ftroubleshooting)\n- [События](\u002Fdocs\u002Fbots\u002Fevents)\n- [Сообщения](\u002Fdocs\u002Fbots\u002Fmessages)\n- [Обновить бота](\u002Fdocs\u002Fbots\u002Fmanagement)\n- [Перенос владения ботом](\u002Fdocs\u002Fbots\u002Fmanagement\u002Ftransfer)\n- [Бот-платформа](\u002Fdocs\u002Fbots)\n- [Лимиты и оптимизация](\u002Fdocs\u002Foptimization)\n","2026-07-07",{}]