Для AI-агентов: markdown этой страницы — /docs-content/chats/copilot.md индекс документации — /llms.txt

CoPilot

Работайте в чатах с CoPilot — ассистентом искусственного интеллекта (AI) Битрикс24: откройте черновой чат CoPilot, смените модель и роль ассистента, попросите переписать ответ и оцените его.

Скоуп: im | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key

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

POST /v1/chats/copilot/draft

Открывает черновой чат CoPilot текущего пользователя. Ответ устроен как загрузка чата: карточка чата, первая страница сообщений, закреплённые сообщения, участники, файлы и блок 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 — личный ключ

Terminal
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-приложение

Terminal
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 Код Описание
HTTP400 КодINVALID_PARAMS ОписаниеmessageLimit или pinLimit не целое число, передано другое поле тела или параметр строки запроса. Проверяется до обращения к Битрикс24
HTTP422 КодBITRIX_ERROR ОписаниеБитрикс24 отказал. Код портала — в error.b24Code. DRAFT_CHAT_NOT_AVAILABLE — черновой чат на портале выключен
HTTP403 КодBITRIX_ACCESS_DENIED ОписаниеПользователю нельзя создавать чаты CoPilot — Битрикс24 отказал с кодом ACCESS_DENIED
HTTP403 КодSCOPE_DENIED ОписаниеAPI-ключ не имеет скоупа im
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеКлюч только для чтения — первый вызов создаёт чат
HTTP401 КодTOKEN_MISSING ОписаниеAPI-ключ не имеет настроенных токенов Битрикс24

Полный список общих ошибок API — Ошибки.

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

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

Дальше — лента. Более старые сообщения читайте лентой в режиме v2 по data.chat.dialogId.

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