imbot.v2.Bot.register
Зарегистрировать бота
Описание
Метод imbot.v2.Bot.register регистрирует нового чат-бота.
Метод идемпотентен: повторный вызов с тем же fields.code от того же приложения возвращает существующего бота без обновления данных. Для обновления используйте imbot.v2.Bot.update.
Если бот работает в составе приложения, события не будут отправляться в приложение, пока установка не завершена. Проверьте установку приложения
Параметры
fields
object
обязательный
Объект с параметрами бота. Описание параметров — ниже
Параметр fields
code
string
обязательный
Уникальный код бота в рамках приложения
botToken
string
необязательный
Уникальный токен авторизации бота. Обязателен при авторизации через вебхук, не нужен для OAuth.
Передайте уникальный botToken — этот ключ будет привязан к чат-боту и потребуется для всех последующих вызовов imbot.v2* через вебхук.
Максимальная длина — 40 символов.
С 06.08.2026 токены длиннее 40 символов будут отклоняться с ошибкой BOT_TOKEN_INVALID_LENGTH. Если вы используете длинный токен — обновите его через imbot.v2.Bot.update до этой даты.
properties
object
обязательный
Свойства профиля бота. Описание параметров — ниже
type
string
необязательный
Тип бота. Описание типов и их поведения — Типы ботов.
Значение по умолчанию: bot
eventMode
string
необязательный
Режим доставки событий.
Допустимые значения:
- fetch — бот забирает события через imbot.v2.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 — используется фон из настроек пользователя. Доступные значения — в таблице фонов. Невалидное значение нормализуется в null
Параметр properties
name
string
обязательный
Имя бота. Отображается в списке чатов и заголовке диалога
lastName
string
необязательный
Фамилия бота
workPosition
string
необязательный
Должность бота (отображается в профиле)
color
string
необязательный
Цвет аватара, доступные цвета.
Если не указан — назначается автоматически
gender
string
необязательный
Пол. Допустимые значения: M, F
avatar
file
необязательный
Аватар. Передавайте строку Base64 без префикса data:*/*;base64,.
Как подготовить данные: Как загружать файлы
Доступные фоны
ID
необязательный
Тема
azure
необязательный
dark
mint
необязательный
dark
steel
необязательный
dark
slate
необязательный
dark
teal
необязательный
dark
cornflower
необязательный
dark
sky
необязательный
light
peach
необязательный
light
frost
необязательный
light
Примеры запроса
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 -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
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);
}
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}")
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.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());
}
}
);
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'];
}
// 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)
Ответ
HTTP-статус: 200
{
"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
{
"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) |

