لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/chats/copilot.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

CoPilot

Work in chats with CoPilot, the Bitrix24 artificial intelligence (AI) assistant: open the CoPilot draft chat, switch the assistant's model and role, ask it to regenerate an answer, and rate the answer.

Scope: im | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

CoPilot draft chat

POST /v1/chats/copilot/draft

Opens the current user's CoPilot draft chat. The response has the same structure as in Load a chat: the chat card, the first page of messages, pinned messages, participants, files and the copilot block. When there is no draft chat yet, the first call creates it.

Parameters

There are no path or query parameters. Any query parameter is rejected with 400 INVALID_PARAMS.

Request fields (body)

The body is optional.

Field Type Required Default Description
FieldmessageLimit Typenumber Requiredno Default— DescriptionHow many messages to return on the first page. From 1 to 200: a value outside the range is clamped; the passed and applied values are in meta.requestedMessageLimit and meta.appliedMessageLimit
FieldpinLimit Typenumber Requiredno Default— DescriptionHow many pinned messages to return. From 1 to 200; the passed and applied values are in meta.requestedPinLimit and meta.appliedPinLimit

Other body fields are rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

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

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/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 — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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('Draft chat:', data.chat.dialogId)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/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('Draft chat:', data.chat.dialogId)

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.chat Typeobject DescriptionThe draft chat card: id, dialogId, name, type, owner, role and other fields
Fielddata.messages Typearray DescriptionThe first page of messages
Fielddata.pins Typearray DescriptionPinned messages
Fielddata.users Typearray DescriptionParticipants mentioned on the page
Fielddata.files Typearray DescriptionFiles of the messages on the page
Fielddata.reactions Typearray DescriptionReactions to the messages on the page
Fielddata.copilot Typeobject DescriptionThe CoPilot block
Fielddata.copilot.chats Typearray DescriptionCoPilot chats on the page: dialogId, role — the role code, engine — the model code, titleIsCustom
Fielddata.copilot.messages Typearray|null DescriptionCoPilot roles of the messages on the page. null if there are no such messages
Fielddata.copilot.engines Typearray|null DescriptionModels of the chats on the page: code, name, supportsReasoning
Fielddata.copilot.roles Typeobject|null DescriptionRoles keyed by role code: code, name, desc, avatar, default, prompts
Fielddata.copilot.aiProvider Typestring DescriptionName of the default model
Fielddata.hasPrevPage Typeboolean DescriptionWhether there are messages older than the first page
Fielddata.hasNextPage Typeboolean DescriptionWhether there are messages newer than the first page
Fieldmeta.requestedMessageLimit Typenumber DescriptionThe messageLimit sent, when it fell outside the range from 1 to 200
Fieldmeta.appliedMessageLimit Typenumber DescriptionThe applied messageLimit — only when it was clamped to a bound
Fieldmeta.requestedPinLimit Typenumber DescriptionThe pinLimit sent, when it fell outside the range from 1 to 200
Fieldmeta.appliedPinLimit Typenumber DescriptionThe applied pinLimit — only when it was clamped to a bound

Response example

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+00:00",
        "text": "Hi! How can I help?",
        "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": "Ready to answer any question in a general format",
          "avatar": { "small": "", "medium": "", "large": "" },
          "default": true,
          "prompts": []
        }
      },
      "aiProvider": "BitrixGPT 5.5"
    },
    "hasPrevPage": false,
    "hasNextPage": false
  }
}

Error response example

422 — the CoPilot draft chat is not available in the Bitrix24 account:

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

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionmessageLimit or pinLimit is not an integer, or another body field or a query parameter was sent. Checked before any call to Bitrix24
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 refused. The portal code is in error.b24Code. DRAFT_CHAT_NOT_AVAILABLE — the draft chat is turned off on the portal
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe user is not allowed to create CoPilot chats — Bitrix24 refused with the ACCESS_DENIED code
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the im scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only — the first call creates a chat
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured

The full list of general API errors — Errors.

Known specifics

Response keys. Keys that name fields are converted to camelCase. Keys that are data stay as they are: the keys of the data.copilot.roles dictionary are role codes, and copilot_assistant arrives as copilot_assistant — the same value that role carries in data.copilot.chats, so you can look up a role directly as roles[role].

Continue in the message history. Load older messages with the message history in the v2 mode using data.chat.dialogId.

See also