For AI agents: markdown of this page — /docs-content-en/chats/messages/command.md documentation index — /llms.txt

Execute a bot command

POST /v1/chats/messages/:messageId/command

Executes a registered bot command in the context of the given chat message.

Parameters

Parameter Type Required Default Description
ParametermessageId (path) Typenumber Requiredyes Default— DescriptionMessage ID, a positive integer — the id field of a message from the message history or chat loading

There are no query parameters. Any query parameter or any body field other than those listed below is rejected with 400 INVALID_PARAMS.

Request fields (body)

Field Type Required Description
FieldbotId Typenumber Requiredyes DescriptionID of the bot that owns the command, a positive integer: the data.commands[].botId field of bot commands in a chat
Fieldcommand Typestring Requiredyes DescriptionThe command, a non-empty string: the data.commands[].command field of bot commands in a chat, for example /echo
Fieldparams Typestring Requiredno DescriptionCommand arguments. The hint for them is the data.commands[].params field of bot commands in a chat

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/chats/messages/1001/command" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"botId": 7, "command": "/echo", "params": "Example"}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/chats/messages/1001/command" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"botId": 7, "command": "/echo", "params": "Example"}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/messages/1001/command', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ botId: 7, command: '/echo', params: 'Example' }),
})

const { success } = await res.json()
console.log('Call accepted:', success)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/messages/1001/command', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ botId: 7, command: '/echo', params: 'Example' }),
})

const { success } = await res.json()
console.log('Call accepted:', success)

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeboolean DescriptionAlways true — the call was accepted

Response example

JSON 
{
  "success": true,
  "data": true
}

Error response example

422 — there is no message with this messageId on the Bitrix24 account:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Incorrect params",
    "b24Code": "PARAMS_ERROR"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionmessageId or botId is not a positive integer, command is missing or empty, params is not a string, or a query parameter or another body field was passed. Checked before any call to Bitrix24
HTTP404 CodeENTITY_NOT_FOUND DescriptionBitrix24 returned "not found". The portal code is in error.b24Code
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 refused the call. The portal code is in error.b24Code, for example PARAMS_ERROR
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied access
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only. Checked before any call to Bitrix24 — see access rights
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the im scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured
HTTP401 CodeMISSING_API_KEY DescriptionX-Api-Key was not passed
HTTP429 CodeRATE_LIMITED DescriptionThe Bitrix24 request limit was exceeded. Retry after the delay in the Retry-After header
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable, returned a server error or did not acknowledge the call
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 accepted the request but did not respond in time, so it is unknown whether the command ran. Retry after the delay in the Retry-After header

The full list of common API errors — Errors.

Known specifics

true does not confirm that the command ran. The response only means the call was accepted. It does not confirm that the command reached the bot or that the bot handled it, and an unknown command may also return true.

botId does not pick a single recipient. In a group chat, the command is matched by name against every bot it is available to.

See also