метод REST scope: imbot

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

Ответ

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 Ошибка при регистрации команды

Что будем искать? Например,Продвижение

Этот сайт использует куки-файлы. Оставаясь на сайте, Вы соглашаетесь на их использование. Для получения дополнительной информации, пожалуйста, ознакомьтесь с политикой в отношении персональных данных.