For AI agents: markdown of this page — /docs-content-en/chats/copilot/engine.md documentation index — /llms.txt

Change the CoPilot model

PUT /v1/chats/:dialogId/copilot/engine

Switches the AI model that CoPilot uses to answer in a chat — the v2 messenger method im.v2.Chat.Copilot.updateEngine. Works only in a CoPilot chat. After the switch Bitrix24 posts a system message about the new model in the chat.

Parameters

Parameter Type Required Description
dialogId (path) string yes Dialog ID of a CoPilot chat — chatN. Get it from data.chat.dialogId of the draft chat or from the recent dialogs with onlyCopilot=true

Query parameters are not accepted and are rejected with 400 INVALID_PARAMS.

Request fields (body)

Field Type Required Description
engineCode string yes Code of an AI model available in the Bitrix24 account. The chat's current model is engine in data.copilot.chats returned by Load a chat

Other body fields are rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl -X PUT https://vibecode.bitrix24.com/v1/chats/chat2001/copilot/engine \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"engineCode": "engine_code"}'

curl — OAuth application

Terminal 
curl -X PUT https://vibecode.bitrix24.com/v1/chats/chat2001/copilot/engine \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"engineCode": "engine_code"}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat2001/copilot/engine', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ engineCode: 'engine_code' }),
})

const { success, data } = await res.json()
console.log('Model switched:', data.result)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat2001/copilot/engine', {
  method: 'PUT',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ engineCode: 'engine_code' }),
})

const { success, data } = await res.json()
console.log('Model switched:', data.result)

Response fields

Field Type Description
success boolean Always true on success
data.result boolean true — the model was switched

Response example

JSON 
{
  "success": true,
  "data": {
    "result": true
  }
}

Error response example

422 — the chat is not a CoPilot chat:

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

Errors

HTTP Code Description
400 INVALID_PARAMS engineCode is missing or is not a non-empty string, or another body field or a query parameter was sent. Checked before any call to Bitrix24
404 ENTITY_NOT_FOUND Bitrix24 returned "not found"; the portal code is in error.b24Code
422 BITRIX_ERROR Bitrix24 refused; the portal code is in error.b24Code: WRONG_MESSAGE_TYPE — not a CoPilot chat, IDENTICAL_ENGINE — the chat already uses this model, ENGINE_NOT_FOUND — no model with this code, COPILOT_NOT_INSTALLED — CoPilot is not installed on the portal
502 ME_ALIAS_RESOLUTION_FAILED Failed to resolve the user when using the me alias
403 SCOPE_DENIED The API key does not have the im scope
403 WRITE_BLOCKED_READONLY_KEY The key is read-only — the call changes the chat
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured

The full list of general API errors — Errors.

Known specifics

A repeated switch is an error. Switching to the model the chat already uses is rejected with IDENTICAL_ENGINE. For an idempotent call, compare engine from data.copilot.chats before switching.

The choice is remembered. Bitrix24 remembers the model as the one the user selected last.

See also