For AI agents: markdown of this page — /docs-content-en/bots/commands/update.md documentation index — /llms.txt

Update a command

PATCH /v1/bots/:botId/commands/:commandId

Updates the parameters of an existing command. Vibecode accepts a flat format and automatically wraps it in fields for Bitrix24.

Request fields (body)

Parameter Type Description
command string New command text without /
title string/object New title. A plain string is stored as the English translation. Use a multilingual object { "en": "...", "de": "..." } to set other languages. Passing null for a key removes the translation: { "en": null }
params string/object New parameter description. A string or an object, same rules as for title
common string "Y" / "N"
hidden string "Y" / "N"
extranetSupport string "Y" / "N"

The table lists every accepted field. A field with any other name is dropped and the request still succeeds: the response includes a warning object with the code UNSUPPORTED_FIELDS_DROPPED and the list of dropped names. Pass the descriptive text of the command in title and the argument hint in params.

Examples

curl — personal key

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/v1/bots/42/commands/7 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": { "en": "Updated help", "de": "Aktualisierte Hilfe" },
    "common": "Y"
  }'

curl — OAuth application

Terminal 
curl -X PATCH https://vibecode.bitrix24.com/v1/bots/42/commands/7 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": { "en": "Updated help", "de": "Aktualisierte Hilfe" },
    "common": "Y"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/42/commands/7', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: { en: 'Updated help', de: 'Aktualisierte Hilfe' },
    common: 'Y',
  }),
})

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

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/42/commands/7', {
  method: 'PATCH',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    title: { en: 'Updated help', de: 'Aktualisierte Hilfe' },
    common: 'Y',
  }),
})

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

Response fields

Field Type Description
data.command.id number Command ID
data.command.botId number Bot ID
data.command.command string Command name with the / prefix
data.command.common boolean Available in all chats, not only in the dialog with the bot
data.command.hidden boolean Hidden from the autocomplete hint
data.command.extranetSupport boolean Available to extranet users
warning.code string UNSUPPORTED_FIELDS_DROPPED. Returned when the request body contained a field outside the "Request fields" table
warning.message string Text listing the dropped fields
warning.droppedFields array Names of the dropped fields

Response example

The request body contained only accepted fields:

JSON 
{
  "success": true,
  "data": {
    "command": {
      "id": 189,
      "botId": 42,
      "command": "/help",
      "common": true,
      "hidden": false,
      "extranetSupport": false
    }
  }
}

The request body contained a description field — the command was updated and the field was dropped:

JSON 
{
  "success": true,
  "data": {
    "command": {
      "id": 189,
      "botId": 42,
      "command": "/help",
      "common": true,
      "hidden": false,
      "extranetSupport": false
    }
  },
  "warning": {
    "code": "UNSUPPORTED_FIELDS_DROPPED",
    "message": "Bitrix24 imbot.v2.Command.update does not accept these fields; they were dropped: description.",
    "droppedFields": ["description"]
  }
}

Error response example

404 — bot not found:

JSON 
{
  "success": false,
  "error": {
    "code": "BOT_NOT_FOUND",
    "message": "Bot 999 not found. Register it first via POST /v1/bots."
  }
}

Errors

HTTP Code Description
400 INVALID_BOT_ID botId is not a number
404 BOT_NOT_FOUND No bot found with this ID
403 BOT_ACCESS_DENIED The bot belongs to a different API key
422 BITRIX_ERROR Bitrix24 error (error text in message)
403 SCOPE_DENIED API key lacks the imbot scope
401 TOKEN_MISSING API key has no configured tokens

Full list of common API errors — Errors.

Known specifics

Removing a translation: pass null for a language key: { "title": { "en": null } } — removes the English translation while keeping the rest.

String flags: common, hidden, extranetSupport accept the strings "Y" / "N" (not booleans).

See also