imbot.v2.Command.register
Зарегистрировать команду
Описание
Метод imbot.v2.Command.register регистрирует слэш-команду бота.
Метод идемпотентный: повторный вызов с тем же command для того же бота от того же приложения возвращает существующую команду без обновления данных. Для обновления используйте imbot.v2.Command.update.
Формат вызова метода был изменен: параметры команды теперь передаются в объекте fields. Старый плоский формат поддерживается до 30.09.2026. Подробнее — Журнал изменений API imbot.v2.
Параметры
botId
integer
обязательный
ID бота
botToken
string
необязательный
Уникальный токен авторизации бота. Обязателен при авторизации через вебхук, не нужен для OAuth.
Передавайте тот же botToken, который был указан при регистрации чат-бота
fields
object
обязательный
Объект с параметрами команды (подробное описание)
Параметр fields
command
string
обязательный
Команда без символа /. Например: help
title
object
необязательный
Заголовок команды на разных языках. Объект {langCode: text}, где langCode — двухбуквенный код языка в нижнем регистре: en, ru, de и так далее.
Отображается в списке доступных команд. Обязателен для видимых команд hidden: false. Для скрытых команд hidden: true можно не указывать
params
object
необязательный
Описание параметров команды на разных языках. Объект {langCode: text}, аналогично title. Отображается как подсказка рядом с командой
common
boolean
необязательный
Общая команда. Допустимые значения: true, false. По умолчанию false. Подробнее — Общие и локальные команды
hidden
boolean
необязательный
Скрытая команда. Допустимые значения: true, false. По умолчанию false
extranetSupport
boolean
необязательный
Поддержка экстранет. Допустимые значения: true, false. По умолчанию false
Примеры запроса
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"botId":456,"botToken":"my_bot_token","fields":{"command":"help","title":{"en":"Show help","ru":"Показать помощь"},"params":{"en":"query","ru":"запрос"}}}' \
https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/imbot.v2.Command.register
curl -X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"botId":456,"fields":{"command":"help","title":{"en":"Show help","ru":"Показать помощь"},"params":{"en":"query","ru":"запрос"}},"auth":"**put_access_token_here**"}' \
https://**put_your_bitrix24_address**/rest/imbot.v2.Command.register
try {
const response = await $b24.callMethod('imbot.v2.Command.register', {
botId: 456,
fields: {
command: 'help',
title: { en: 'Show help', ru: 'Показать помощь' },
params: { en: 'query', ru: 'запрос' },
},
});
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.command.register(
bot_id=456,
fields={
"command": "help",
"title": {
"en": "Show help",
"ru": "Показать помощь",
},
"params": {
"en": "query",
"ru": "точно",
},
},
).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.Command.register',
[
'botId' => 456,
'fields' => [
'command' => 'help',
'title' => ['en' => 'Show help', 'ru' => 'Показать помощь'],
'params' => ['en' => 'query', 'ru' => 'запрос'],
],
]
);
$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.Command.register',
{
botId: 456,
fields: {
command: 'help',
title: { en: 'Show help', ru: 'Показать помощь' },
params: { en: 'query', ru: 'запрос' },
},
},
function(result) {
if (result.error()) {
console.error(result.error().ex);
} else {
console.log(result.data());
}
}
);
require_once('crest.php');
$result = CRest::call(
'imbot.v2.Command.register',
[
'botId' => 456,
'fields' => [
'command' => 'help',
'title' => ['en' => 'Show help', 'ru' => 'Показать помощь'],
'params' => ['en' => 'query', 'ru' => 'запрос'],
],
]
);
if (!empty($result['error'])) {
echo 'Error: '. $result['error_description'];
} else {
echo 'Command ID: '. $result['result']['command']['id'];
}
// client и ctx уже созданы — см. раздел «SDK для Go»
res, err := client.Core().Call(ctx, "imbot.v2.Command.register", b24.Params{
"botId": 456,
"botToken": "my_bot_token",
"fields": b24.Params{
"command": "help",
"title": b24.Params{
"en": "Show help",
"ru": "Показать помощь",
},
"params": b24.Params{
"en": "query",
"ru": "запрос",
},
},
})
if err != nil {
return fmt.Errorf("imbot.v2.Command.register: %w", err)
}
// Метод заворачивает ответ в объект с ключом "command".
raw, ok := b24.Unwrap(res.Result, "command")
if !ok {
return fmt.Errorf("в ответе нет ключа command")
}
var item struct {
ID b24.ID `json:"id"`
BotID b24.ID `json:"botId"`
Command string `json:"command"`
Common bool `json:"common"`
Hidden bool `json:"hidden"`
ExtranetSupport bool `json:"extranetSupport"`
}
if err := json.Unmarshal(raw, &item); err != nil {
return fmt.Errorf("разбор ответа: %w", err)
}
fmt.Println(item.ID, item.BotID)
Ответ
HTTP-статус: 200
{
"result": {
"command": {
"id": 42,
"botId": 456,
"command": "/help",
"common": false,
"hidden": false,
"extranetSupport": false
}
},
"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": "COMMAND_REQUIRED",
"error_description": "Command is required"
}
| Код | Описание | Значение |
|---|---|---|
BOT_TOKEN_NOT_SPECIFIED |
Bot token is not specified | Не указан botToken. Обязателен при авторизации через вебхук |
BOT_ID_REQUIRED |
Bot ID is required | Не указан botId |
BOT_NOT_FOUND |
Bot not found | Бот не найден |
BOT_OWNERSHIP_ERROR |
Bot is registered by another application | Бот зарегистрирован другим приложением |
COMMAND_NAME_INVALID |
Command name is invalid | Имя команды должно быть строкой |
COMMAND_REQUIRED |
Command is required | Не указана команда (fields.command) |
COMMAND_TITLE_REQUIRED |
Command title is required | Не указан fields.title для видимой команды fields.hidden: false |
COMMAND_REGISTER_FAILED |
Command registration failed | Ошибка при регистрации команды |

