Для AI-агентов: markdown этой страницы — /docs-content/bots/commands/list.md индекс документации — /llms.txt

Список команд

GET /v1/bots/:botId/commands

Возвращает зарегистрированные команды бота вместе с системными командами портала.

Возможная задержка после мутаций

Вайбкод не кеширует этот ответ. Однако сам Битрикс24 держит свой кеш списка команд и не всегда обновляет его сразу после регистрации, обновления или удаления команды. В течение нескольких секунд (иногда минут) после успешной мутации GET может возвращать:

удалённые команды (их id ещё видны в списке)
старые значения title / params / common для только что обновлённой команды
отсутствие только что зарегистрированной команды.

При этом сама команда уже действует на стороне Битрикс24 (на неё реагирует событие ONIMBOTV2COMMANDADD, бот её обрабатывает) — расхождение видно только в этом GET.

Что делать

Не использовать GET /commands как единственный источник правды сразу после мутации. Опирайтесь на ответ самой мутации: POST возвращает данные с новым id, PATCH — обновлённую команду, DELETE — признак успеха.
Если нужна синхронизация со списком (например для сверки интерфейса с реальным состоянием), запросите GET повторно через 10–30 секунд.
Если расхождение сохраняется дольше минуты, это уже не штатная задержка. Приложите к обращению в поддержку botId, время мутации и то, что именно ожидалось и что получено.

Принудительно сбросить этот кеш на стороне Битрикс24 нельзя. Если список не обновился — повторите GET через несколько секунд.

Параметры

Параметр	Тип	Обяз.	Описание
`botId` (path)	number	да	ID бота

Примеры

curl — личный ключ

Terminal

curl https://vibecode.bitrix24.tech/v1/bots/42/commands \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal

curl https://vibecode.bitrix24.tech/v1/bots/42/commands \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

javascript

const res = await fetch('https://vibecode.bitrix24.tech/v1/bots/42/commands', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Команды:', data.commands)

JavaScript — OAuth-приложение

javascript

const res = await fetch('https://vibecode.bitrix24.tech/v1/bots/42/commands', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Поля ответа

Поле	Тип	Описание
`success`	boolean	Всегда `true` при успехе
`data`	object	Результат запроса
`data.commands`	array	Команды бота и системные команды портала
`data.commands[].id`	number \| string	ID команды. У команды бота — число, у системной команды портала — строка вида `def0`
`data.commands[].botId`	number	ID бота — владельца команды. `0` у системной команды портала
`data.commands[].command`	string	Текст команды, начинается с `/`, например `/help`
`data.commands[].category`	string	Название группы команды в списке команд. У команды бота — имя бота
`data.commands[].common`	string	`Y` — команда доступна во всех чатах, `N` — только в личном диалоге с ботом и чатах с ботом
`data.commands[].context`	string	Контекст команды. Пустая строка, если не задан
`data.commands[].title`	string	Описание команды на языке портала
`data.commands[].params`	string	Подсказка к параметрам команды на языке портала. Пустая строка, если не задана
`data.commands[].extranet`	string	`Y` — команда доступна экстранет-пользователям, `N` — нет

Пример ответа

Показаны две системные команды портала из шести и команда бота:

JSON

{
  "success": true,
  "data": {
    "commands": [
      {
        "id": "def0",
        "botId": 0,
        "command": "/me",
        "category": "Чат и звонки",
        "common": "Y",
        "context": "",
        "title": "Текст будет выделен курсивом",
        "params": "текст",
        "extranet": "Y"
      },
      {
        "id": "def3",
        "botId": 0,
        "command": "/rename",
        "category": "Чаты",
        "common": "Y",
        "context": "chat",
        "title": "Изменение заголовка чата",
        "params": "новый заголовок",
        "extranet": "Y"
      },
      {
        "id": 229,
        "botId": 42,
        "command": "/help",
        "category": "Техподдержка",
        "common": "Y",
        "context": "",
        "title": "Помощь",
        "params": "тема",
        "extranet": "N"
      }
    ]
  }
}

Пример ответа при ошибке

404 — бот не найден: