Для 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 — личный ключ
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-приложение
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 — личный ключ
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-приложение
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 — только если он был приведён к границе |
Пример ответа
{
"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 на портале недоступен:
{
"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.