## Выполнить команду бота

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

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

## Параметры

| Параметр | Тип | Обяз. | По умолч. | Описание |
|----------|-----|:-----:|-----------|---------|
| `messageId` (path) | number | да | — | ID сообщения, положительное целое — поле `id` сообщения из [ленты](/docs/chats/messages/list) или [загрузки чата](/docs/chats/messages/load) |

Параметров запроса нет. Любой параметр запроса или поле тела, кроме перечисленных ниже, отклоняется с `400 INVALID_PARAMS`.

## Поля запроса (body)

| Поле | Тип | Обяз. | Описание |
|------|-----|:-----:|---------|
| `botId` | number | да | ID бота — владельца команды, положительное целое: поле `data.commands[].botId` [команд ботов в чате](/docs/chats/commands) |
| `command` | string | да | Команда, непустая строка: поле `data.commands[].command` [команд ботов в чате](/docs/chats/commands), например `/echo` |
| `params` | string | нет | Аргументы команды. Подсказка к ним — поле `data.commands[].params` [команд ботов в чате](/docs/chats/commands) |

## Примеры

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

```bash
curl -X POST "https://vibecode.bitrix24.tech/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-приложение

```bash
curl -X POST "https://vibecode.bitrix24.tech/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 — личный ключ

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/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('Вызов принят:', success)
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/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('Вызов принят:', success)
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data` | boolean | Всегда `true` — вызов принят |

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

```json
{
  "success": true,
  "data": true
}
```

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

422 — сообщения с таким `messageId` нет на портале:

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

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | `messageId` или `botId` не положительное целое, `command` не передан или пуст, `params` не строка, передан параметр запроса или другое поле тела. Проверяется до обращения к Битрикс24 |
| 404 | `ENTITY_NOT_FOUND` | Битрикс24 вернул «не найдено». Код портала — в `error.b24Code` |
| 422 | `BITRIX_ERROR` | Битрикс24 отказал. Код портала — в `error.b24Code`, например `PARAMS_ERROR` |
| 403 | `BITRIX_ACCESS_DENIED` | Битрикс24 отказал в доступе |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ только для чтения. Проверяется до обращения к Битрикс24 — см. [права доступа](/docs/access-rights) |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `im` |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов Битрикс24 |
| 401 | `MISSING_API_KEY` | Не передан `X-Api-Key` |
| 429 | `RATE_LIMITED` | Превышен лимит запросов к Битрикс24. Повторите вызов после паузы из заголовка `Retry-After` |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 недоступен, ответил ошибкой сервера или не подтвердил вызов |
| 503 | `BITRIX_TIMEOUT` | Битрикс24 принял запрос, но не ответил вовремя: выполнена ли команда, неизвестно. Повторите вызов после паузы из заголовка `Retry-After` |

Полный список общих ошибок API — [Ошибки](/docs/errors).

## Известные особенности

**`true` не подтверждает выполнение команды.** Ответ означает только, что вызов принят. Доставку команды боту и её обработку он не подтверждает, а неизвестная команда тоже может вернуть `true`.

**`botId` не выбирает единственного получателя.** В групповом чате команда сопоставляется по имени со всеми ботами, которым она доступна.

## Смотрите также

- [Команды ботов в чате](/docs/chats/commands)
- [Ошибки](/docs/errors)