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
messageId (path) number yes — Message 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
botId number yes ID of the bot that owns the command, a positive integer: the data.commands[].botId field of bot commands in a chat
command string yes The command, a non-empty string: the data.commands[].command field of bot commands in a chat, for example /echo
params string no Command 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
success boolean Always true on success
data boolean Always 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
400 INVALID_PARAMS messageId 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
404 ENTITY_NOT_FOUND Bitrix24 returned "not found". The portal code is in error.b24Code
422 BITRIX_ERROR Bitrix24 refused the call. The portal code is in error.b24Code, for example PARAMS_ERROR
403 BITRIX_ACCESS_DENIED Bitrix24 denied access
403 WRITE_BLOCKED_READONLY_KEY The key is read-only. Checked before any call to Bitrix24 — see access rights
403 SCOPE_DENIED The API key does not have the im scope
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured
401 MISSING_API_KEY X-Api-Key was not passed
429 RATE_LIMITED The Bitrix24 request limit was exceeded. Retry after the delay in the Retry-After header
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable, returned a server error or did not acknowledge the call
503 BITRIX_TIMEOUT Bitrix24 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