## Получить бота

`GET /v1/bots/:botId`

Получает актуальные данные о боте из Битрикс24 (живой запрос, не из кэша).

## Параметры

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

## Примеры

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

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

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

```bash
curl https://vibecode.bitrix24.tech/v1/bots/42 \
  -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', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Бот:', data)
```

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

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

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

Ответ содержит два объекта: `data.bot` — параметры бота, `data.users` — массив пользователей Битрикс24, представляющих бота. В массиве один элемент — учётная запись бота-пользователя.

| Поле | Тип | Описание |
|------|-----|---------|
| `data.bot.id` | number | ID бота на портале Битрикс24 |
| `data.bot.code` | string | Уникальный код бота |
| `data.bot.type` | string | Тип бота: `bot`, `personal`, `supervisor`, `openline` |
| `data.bot.isHidden` | boolean | Скрыт из списка контактов |
| `data.bot.isSupportOpenline` | boolean | Поддержка открытых линий |
| `data.bot.isReactionsEnabled` | boolean | Разрешены реакции на сообщения |
| `data.bot.backgroundId` | string | Фон чата. Приходит `null`, когда не задан |
| `data.bot.language` | string | Язык бота, например `ru` |
| `data.bot.moduleId` | string | Модуль, зарегистрировавший бота, например `rest` |
| `data.bot.eventMode` | string | Режим событий: `fetch` или `webhook` |
| `data.bot.countMessage` | number | Счётчик сообщений |
| `data.bot.countCommand` | number | Счётчик команд |
| `data.bot.countChat` | number | Счётчик чатов |
| `data.bot.countUser` | number | Счётчик пользователей |
| `data.users[].id` | number | ID пользователя-бота. Совпадает с `data.bot.id` |
| `data.users[].name` | string | Полное имя |
| `data.users[].firstName` | string | Имя |
| `data.users[].lastName` | string | Фамилия. Пустая строка, если не задана |
| `data.users[].workPosition` | string | Должность |
| `data.users[].color` | string | Цвет аватара в формате HEX, например `#29619b` |
| `data.users[].avatar` | string | URL аватара. Пустая строка, если не задан |
| `data.users[].gender` | string | Пол: `M` или `F` |
| `data.users[].active` | boolean | Активен ли пользователь |
| `data.users[].bot` | boolean | Признак бота |
| `data.users[].departments` | array | Подразделения. Пустой массив, если их нет |
| `data.users[].lastActivityDate` | string \| null | Время последней активности. `null`, если активности не было |

Массив `data.users` несёт и другие стандартные поля пользователя Битрикс24 — `birthday`, `phones`, `website`, `email`, `status`, `mobileLastDate`, `desktopLastDate`. О том, как кодируются незаполненные значения, — в разделе «Известные особенности».

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

```json
{
  "success": true,
  "data": {
    "bot": {
      "id": 42,
      "code": "support_bot",
      "type": "bot",
      "isHidden": false,
      "isSupportOpenline": false,
      "isReactionsEnabled": true,
      "backgroundId": null,
      "language": "ru",
      "moduleId": "rest",
      "eventMode": "fetch",
      "countMessage": 0,
      "countCommand": 0,
      "countChat": 0,
      "countUser": 0
    },
    "users": [
      {
        "id": 42,
        "active": true,
        "name": "Техподдержка",
        "firstName": "Техподдержка",
        "lastName": "",
        "workPosition": "Помощник по техническим вопросам",
        "color": "#29619b",
        "avatar": "",
        "gender": "M",
        "bot": true,
        "departments": [],
        "lastActivityDate": null,
        "phones": []
      }
    ]
  }
}
```

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

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

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

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `INVALID_BOT_ID` | `botId` не является числом |
| 404 | `BOT_NOT_FOUND` | Бот не найден — зарегистрируйте через `POST /v1/bots` |
| 403 | `BOT_ACCESS_DENIED` | Бот принадлежит другому API-ключу. Вернуть управление — [Восстановление доступа к боту](/docs/bots/ownership-recovery) |
| 403 | `B24_MARKET_SUBSCRIPTION_REQUIRED` | Бот припаркован из-за неактивной подписки Маркетплейса; порядок восстановления — в разделе ошибок подписки |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `imbot` |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |

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

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

**Незаполненные значения приходят в предсказуемой форме.** Пустые даты `lastActivityDate`, `mobileLastDate` и `desktopLastDate` платформа приводит к `null`, а незаполненный список `phones` — к пустому массиву, поэтому `phones.map(...)` работает без предварительной проверки. Пустые строковые поля `lastName`, `avatar`, `birthday`, `website`, `email` приходят пустой строкой, `departments` — пустым массивом, а незаданный `backgroundId` в `data.bot` — `null`.

**Цвет аватара возвращается в HEX.** При записи `color` принимает имя из палитры (`AZURE`, `MINT`, …), но в ответе `data.users[].color` приходит уже как HEX-строка, например `#29619b`. Прочитать обратно записанное имя из палитры нельзя.

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

- [Список ботов](/docs/bots/management/list)
- [Обновить бота](/docs/bots/management/update)
- [Восстановление доступа к боту](/docs/bots/ownership-recovery)
- [События](/docs/bots/events)
- [Лимиты и оптимизация](/docs/optimization)