## Черновой чат CoPilot

`POST /v1/chats/copilot/draft`

Открывает черновой чат CoPilot текущего пользователя. Ответ устроен как [загрузка чата](/docs/chats/messages/load): карточка чата, первая страница сообщений, закреплённые сообщения, участники, файлы и блок `copilot`. Если чернового чата ещё нет, первый вызов его создаёт.

## Параметры

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

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

Тело необязательно.

| Поле | Тип | Обяз. | По умолч. | Описание |
|------|-----|:-----:|-----------|---------|
| `messageLimit` | number | нет | — | Сколько сообщений взять на первую страницу. От 1 до 200: значение вне диапазона срезается, переданное и применённое значения — в `meta.requestedMessageLimit` и `meta.appliedMessageLimit` |
| `pinLimit` | number | нет | — | Сколько закреплённых сообщений вернуть. От 1 до 200, переданное и применённое значения — в `meta.requestedPinLimit` и `meta.appliedPinLimit` |

Другие поля тела отклоняются с `400 INVALID_PARAMS`.

## Примеры

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

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/chats/copilot/draft \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messageLimit": 20}'
```

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

```bash
curl -X POST https://vibecode.bitrix24.tech/v1/chats/copilot/draft \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messageLimit": 20}'
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/copilot/draft', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ messageLimit: 20 }),
})

const { data } = await res.json()
console.log('Черновой чат:', data.chat.dialogId)
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/copilot/draft', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ messageLimit: 20 }),
})

const { data } = await res.json()
console.log('Черновой чат:', data.chat.dialogId)
```

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

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data.chat` | object | Карточка чернового чата: `id`, `dialogId`, `name`, `type`, `owner`, `role` и другие поля |
| `data.messages` | array | Первая страница сообщений |
| `data.pins` | array | Закреплённые сообщения |
| `data.users` | array | Участники, упомянутые на странице |
| `data.files` | array | Файлы сообщений страницы |
| `data.reactions` | array | Реакции на сообщения страницы |
| `data.copilot` | object | Блок CoPilot |
| `data.copilot.chats` | array | Чаты CoPilot страницы: `dialogId`, `role` — код роли, `engine` — код модели, `titleIsCustom` |
| `data.copilot.messages` | array\|null | Роли CoPilot у сообщений страницы. `null`, если таких сообщений нет |
| `data.copilot.engines` | array\|null | Модели чатов страницы: `code`, `name`, `supportsReasoning` |
| `data.copilot.roles` | object\|null | Роли по коду роли: `code`, `name`, `desc`, `avatar`, `default`, `prompts` |
| `data.copilot.aiProvider` | string | Название модели по умолчанию |
| `data.hasPrevPage` | boolean | Есть сообщения старше первой страницы |
| `data.hasNextPage` | boolean | Есть сообщения новее первой страницы |
| `meta.requestedMessageLimit` | number | Переданный `messageLimit`, когда он вышел за диапазон от 1 до 200 |
| `meta.appliedMessageLimit` | number | Применённое значение `messageLimit` — только если он был приведён к границе |
| `meta.requestedPinLimit` | number | Переданный `pinLimit`, когда он вышел за диапазон от 1 до 200 |
| `meta.appliedPinLimit` | number | Применённое значение `pinLimit` — только если он был приведён к границе |

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

```json
{
  "success": true,
  "data": {
    "chat": {
      "id": 2001,
      "dialogId": "chat2001",
      "name": "CoPilot",
      "type": "copilot",
      "owner": 5,
      "role": "owner"
    },
    "messages": [
      {
        "id": 9001,
        "chatId": 2001,
        "authorId": 0,
        "date": "2026-09-25T10:00:00+03:00",
        "text": "Здравствуйте! Чем помочь?",
        "params": {}
      }
    ],
    "pins": [],
    "users": [],
    "files": [],
    "reactions": [],
    "copilot": {
      "chats": [
        { "dialogId": "chat2001", "role": "copilot_assistant", "engine": "b24ai", "titleIsCustom": false }
      ],
      "messages": null,
      "engines": [
        { "code": "b24ai", "name": "BitrixGPT 5.5", "supportsReasoning": true }
      ],
      "roles": {
        "copilot_assistant": {
          "code": "copilot_assistant",
          "name": "BitrixGPT",
          "desc": "Готов отвечать на все вопросы в общем формате",
          "avatar": { "small": "", "medium": "", "large": "" },
          "default": true,
          "prompts": []
        }
      },
      "aiProvider": "BitrixGPT 5.5"
    },
    "hasPrevPage": false,
    "hasNextPage": false
  }
}
```

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

422 — черновой чат CoPilot на портале недоступен:

```json
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "DRAFT_CHAT_NOT_AVAILABLE",
    "b24Code": "DRAFT_CHAT_NOT_AVAILABLE"
  }
}
```

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | `messageLimit` или `pinLimit` не целое число, передано другое поле тела или параметр строки запроса. Проверяется до обращения к Битрикс24 |
| 422 | `BITRIX_ERROR` | Битрикс24 отказал. Код портала — в `error.b24Code`. `DRAFT_CHAT_NOT_AVAILABLE` — черновой чат на портале выключен |
| 403 | `BITRIX_ACCESS_DENIED` | Пользователю нельзя создавать чаты CoPilot — Битрикс24 отказал с кодом `ACCESS_DENIED` |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `im` |
| 403 | `WRITE_BLOCKED_READONLY_KEY` | Ключ только для чтения — первый вызов создаёт чат |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов Битрикс24 |

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

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

**Ключи ответа.** Ключи-имена полей приводятся к camelCase. Ключи-данные остаются как есть: ключи словаря `data.copilot.roles` — коды ролей, и `copilot_assistant` приходит как `copilot_assistant` — тем же значением, что `role` в `data.copilot.chats`, поэтому роль находится прямым обращением `roles[role]`.

**Дальше — лента.** Более старые сообщения читайте [лентой в режиме v2](/docs/chats/messages/list) по `data.chat.dialogId`.

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

- [CoPilot](/docs/chats/copilot)
- [Загрузка чата](/docs/chats/messages/load)
- [Сменить модель CoPilot](/docs/chats/copilot/engine)