# imbot.v2.Bot.register URL: https://chugunov.pro/api-bitrix24/chat-bots/chat-bots-v2/imbot.v2/bots/bot-register/ Проверено на Битрикс24 REST API, обновлено 11.09.2026 (ревизия источника fb39d6c). Источник: официальная документация Битрикс24 (bitrix-tools/b24-rest-docs, лицензия MIT, © Bitrix). Справочник независимый, официальной документацией не является. Зарегистрировать бота Scope: `imbot` Кто может выполнять метод: авторизованный пользователь ## Описание Метод `imbot.v2.Bot.register` регистрирует нового чат-бота. Метод идемпотентен: повторный вызов с тем же `fields.code` от того же приложения возвращает существующего бота без обновления данных. Для обновления используйте [imbot.v2.Bot.update](https://chugunov.pro/api-bitrix24/chat-bots/chat-bots-v2/imbot.v2/bots/bot-update/). Если бот работает в составе приложения, события не будут отправляться в приложение, пока установка не завершена. [Проверьте установку приложения](https://apidocs.bitrix24.ru/settings/app-installation/installation-finish.html) ## Параметры - `fields` `object` — обязательный. Объект с параметрами бота. Описание параметров — [ниже](#fields) ### Параметр fields - `code` `string` — обязательный. Уникальный код бота в рамках приложения - `botToken` `string` — необязательный. Уникальный токен авторизации бота. Обязателен при авторизации через вебхук, не нужен для OAuth. Передайте уникальный botToken — этот ключ будет привязан к чат-боту и потребуется для всех последующих вызовов imbot.v2* через вебхук. Максимальная длина — **40 символов**. С 06.08.2026 токены длиннее 40 символов будут **отклоняться** с ошибкой `BOT_TOKEN_INVALID_LENGTH`. Если вы используете длинный токен — обновите его через [imbot.v2.Bot.update](https://chugunov.pro/api-bitrix24/chat-bots/chat-bots-v2/imbot.v2/bots/bot-update/) до этой даты. - `properties` `object` — обязательный. Свойства профиля бота. Описание параметров — [ниже](#properties) - `type` `string` — необязательный. Тип бота. Описание типов и их поведения — [Типы ботов](https://chugunov.pro/api-bitrix24/chat-bots/chat-bots-v2/#bot-types). Значение по умолчанию: `bot` - `eventMode` `string` — необязательный. Режим доставки событий. Допустимые значения: - `fetch` — бот забирает события через [imbot.v2.Event.get](https://chugunov.pro/api-bitrix24/chat-bots/chat-bots-v2/imbot.v2/events/event-get/) - `webhook` — события отправляются POST-запросом на `webhookUrl` Значение по умолчанию: `fetch` - `webhookUrl` `string` — необязательный. URL обработчика событий бота. Обязателен при `eventMode = webhook` - `isHidden` `boolean` — необязательный. Скрытый бот. Допустимые значения: `true`, `false`. По умолчанию `false` - `isReactionsEnabled` `boolean` — необязательный. Включить поддержку реакций. Допустимые значения: `true`, `false`. По умолчанию `true` - `isSupportOpenline` `boolean` — необязательный. Включить поддержку Открытых линий. Допустимые значения: `true`, `false`. По умолчанию `false` - `backgroundId` `string` — необязательный. Фон чата бота. По умолчанию `null` — используется фон из настроек пользователя. Доступные значения — в [таблице фонов](#backgrounds). Невалидное значение нормализуется в `null` ### Параметр properties - `name` `string` — обязательный. Имя бота. Отображается в списке чатов и заголовке диалога - `lastName` `string` — необязательный. Фамилия бота - `workPosition` `string` — необязательный. Должность бота (отображается в профиле) - `color` `string` — необязательный. Цвет аватара, [доступные цвета](https://chugunov.pro/api-bitrix24/chat-bots/chat-bots-v2/imbot.v2/chats/chat-add/#available-colors). Если не указан — назначается автоматически - `gender` `string` — необязательный. Пол. Допустимые значения: `M`, `F` - `avatar` `file` — необязательный. Аватар. Передавайте строку Base64 без префикса `data:*/*;base64,`. Как подготовить данные: [Как загружать файлы](https://apidocs.bitrix24.ru/api-reference/files/how-to-upload-files.html#kak-kodirovat-fajl-v-base64) ### Доступные фоны - `ID` — необязательный. **Тема** - `azure` — необязательный. dark - `mint` — необязательный. dark - `steel` — необязательный. dark - `slate` — необязательный. dark - `teal` — необязательный. dark - `cornflower` — необязательный. dark - `sky` — необязательный. light - `peach` — необязательный. light - `frost` — необязательный. light ## Ответ HTTP-статус: 200 ```json { "result": { "bot": { "id": 456, "code": "support_bot", "type": "bot", "isHidden": false, "isSupportOpenline": false, "isReactionsEnabled": true, "backgroundId": null, "language": "en", "moduleId": "rest", "eventMode": "fetch", "countMessage": 0, "countCommand": 0, "countChat": 0, "countUser": 0 }, "users": [ { "id": 456, "active": true, "name": "Support Bot", "firstName": "Support", "lastName": "Bot", "workPosition": "AI Assistant", "color": "#df532d", "avatar": "", "gender": "M", "birthday": "", "extranet": false, "bot": true, "connector": false, "externalAuthId": "bot", "status": "online", "idle": false, "lastActivityDate": "2025-01-15T10:30:00+03:00", "absent": false, "departments": [1], "phones": false, "type": "bot" } ] }, "time": { "start": 1728626400.123, "finish": 1728626400.234, "duration": 0.111, "processing": 0.045, "date_start": "2024-10-11T10:00:00+03:00", "date_finish": "2024-10-11T10:00:00+03:00" } } ``` ## Ошибки HTTP-статус: 400 ```json { "error": "BOT_CODE_REQUIRED", "error_description": "Bot code is required" } ``` - `BOT_TOKEN_NOT_SPECIFIED` — Bot token is not specified. Не указан `fields.botToken`. Обязателен при авторизации через вебхук - `BOT_CODE_REQUIRED` — Bot code is required. Не указан код бота (`fields.code`) - `BOT_PROPERTIES_REQUIRED` — Bot properties are required. Не указаны свойства бота (имя) - `BOT_CODE_ALREADY_TAKEN` — Bot code is already taken. Код бота уже занят другим приложением - `BOT_INVALID_TYPE` — Invalid bot type. Невалидный тип бота. Допустимые значения: `bot`, `network`, `openline`, `supervisor`, `personal` - `BOT_INVALID_EVENT_MODE` — Invalid event mode. Невалидный режим доставки событий. Допустимые значения: `fetch`, `webhook` - `BOT_WEBHOOK_URL_REQUIRED` — Webhook URL is required. Не указан `fields.webhookUrl` при `fields.eventMode = webhook` - `BOT_REGISTER_FAILED` — Bot registration failed. Ошибка регистрации бота - `BOT_INVALID_CALLBACK` — Invalid callback URL. Невалидный URL обработчика - `BOT_LIMIT_EXCEEDED` — Bot limit exceeded. Превышен лимит ботов приложения (100 ботов) - `BOT_AVATAR_INCORRECT_TYPE` — Avatar must be an image. Аватар должен быть изображением (`image/*`) - `BOT_AVATAR_INCORRECT_SIZE` — Avatar exceeds maximum size. Размер аватара превышает максимум (5000×5000 px) ## Примеры запроса ### cURL (Webhook) ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "fields":{ "code":"support_bot", "botToken":"my_bot_token", "properties":{"name":"Support Bot","workPosition":"AI Assistant"}, "type":"bot", "eventMode":"fetch" } }' \ https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/imbot.v2.Bot.register ``` ### cURL (OAuth) ```bash curl -X POST \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "fields":{ "code":"support_bot", "properties":{"name":"Support Bot","workPosition":"AI Assistant"}, "type":"bot", "eventMode":"fetch" }, "auth":"**put_access_token_here**" }' \ https://**put_your_bitrix24_address**/rest/imbot.v2.Bot.register ``` ### JS ```js try { const response = await $b24.callMethod('imbot.v2.Bot.register', { fields: { code: 'support_bot', properties: { name: 'Support Bot', workPosition: 'AI Assistant', }, type: 'bot', eventMode: 'fetch', }, }); const { result } = response.getData(); console.log('result:', result); } catch (error) { console.error('Error:', error); } ``` ### Python ```python from b24pysdk.errors import BitrixAPIError, BitrixSDKException try: bitrix_response = client.imbot.v2.bot.register( fields={ "code": "support_bot", "properties": { "name": "Support Bot", "workPosition": "AI Assistant", }, "type": "bot", "eventMode": "fetch", }, ).response result = bitrix_response.result print(result) except BitrixAPIError as error: print( "Ошибка Bitrix API", f"error: {error.error}", f"error_description: {error.error_description}", sep="\n", ) except BitrixSDKException as error: print(f"Ошибка Bitrix SDK: {error.message}") except Exception as error: print(f"Непредвиденная ошибка: {error}") ``` ### PHP ```php try { $response = $b24Service ->core ->call( 'imbot.v2.Bot.register', [ 'fields' => [ 'code' => 'support_bot', 'properties' => [ 'name' => 'Support Bot', 'workPosition' => 'AI Assistant', ], 'type' => 'bot', 'eventMode' => 'fetch', ], ] ); $result = $response ->getResponseData() ->getResult(); echo 'result: '. print_r($result, true); } catch (Throwable $exception) { error_log($exception->getMessage()); echo 'Error: '. $exception->getMessage(); } ``` ### BX24.js ```js BX24.callMethod( 'imbot.v2.Bot.register', { fields: { code: 'support_bot', properties: { name: 'Support Bot', workPosition: 'AI Assistant', }, type: 'bot', eventMode: 'fetch', }, }, function(result) { if (result.error()) { console.error(result.error().ex); } else { console.log(result.data()); } } ); ``` ### PHP CRest ```php require_once('crest.php'); $result = CRest::call( 'imbot.v2.Bot.register', [ 'fields' => [ 'code' => 'support_bot', 'properties' => [ 'name' => 'Support Bot', 'workPosition' => 'AI Assistant', ], 'type' => 'bot', 'eventMode' => 'fetch', ], ] ); if (!empty($result['error'])) { echo 'Error: '. $result['error_description']; } else { echo 'Bot ID: '. $result['result']['bot']['id']; } ``` ### Go ```go // client и ctx уже созданы — см. раздел «SDK для Go» res, err := client.Core().Call(ctx, "imbot.v2.Bot.register", b24.Params{ "fields": b24.Params{ "code": "support_bot", "botToken": "my_bot_token", "properties": b24.Params{ "name": "Support Bot", "workPosition": "AI Assistant", }, "type": "bot", "eventMode": "fetch", }, }) if err != nil { return fmt.Errorf("imbot.v2.Bot.register: %w", err) } // Форма ответа показана ниже на этой странице. fmt.Printf("%s\n", res.Result) ``` Оригинал в официальной документации: https://apidocs.bitrix24.ru/api-reference/chat-bots/chat-bots-v2/imbot.v2/bots/bot-register.html