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

Add chats to a folder

POST /v1/chats/folders/:folderId/chats

Adds chats to the current user's personal folder by chat IDs or dialog IDs.

The call is a write: a read-only key gets 403 WRITE_BLOCKED_READONLY_KEY before any call to Bitrix24. To create a folder, see Create a chat folder. To replace its contents as a whole, see Update a chat folder.

Parameters

Parameter Type Required Description
ParameterfolderId (path) Typenumber Requiredyes DescriptionPersonal folder ID — the id of a folder with type: "personal" from GET /v1/chats/folders

Request fields (body)

Field Type Required Description
FieldchatIds Typenumber[] Requiredno DescriptionChat IDs — the chatId field of recent dialogs. Each element is a positive integer: a number or a string of digits without leading zeros
FielddialogIds Typestring[] Requiredno DescriptionDialog IDs: chatXXX for a group chat — the dialogId field of recent dialogs, or a user ID for a direct dialog — from the user list. Each element is a non-empty string of up to 64 characters without commas or surrounding spaces. The me alias is not accepted — pass the user ID

At least one ID in chatIds or dialogIds is required. There are no query parameters. Any query parameter or other body field is rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/chats/folders/16/chats" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chatIds": [42], "dialogIds": ["chat57"]}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/chats/folders/16/chats" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chatIds": [42], "dialogIds": ["chat57"]}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/folders/16/chats', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ chatIds: [42], dialogIds: ['chat57'] }),
})

const { success } = await res.json()

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/folders/16/chats', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ chatIds: [42], dialogIds: ['chat57'] }),
})

const { success } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.result Typeboolean Descriptiontrue — the write succeeded. The resulting folder contents — GET /v1/chats/folders/:folderId

Response example

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

Error response example

422 — chats cannot be added to a system folder:

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

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionfolderId is not a positive integer; neither chatIds nor dialogIds contains an ID; a list is not an array or has an invalid element; a query parameter or an unknown body field was sent; the body is not a JSON object. Checked before any call to Bitrix24
HTTP404 CodeENTITY_NOT_FOUND DescriptionBitrix24 answered "not found"; the portal code is in error.b24Code
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error; the portal code is in error.b24Code: FOLDER_NOT_FOUND — no such folder, FOLDER_ACCESS_DENIED — another user's folder, FOLDER_SYSTEM_MUTATION_FORBIDDEN — a system folder's contents cannot be changed, FOLDER_CHATS_LIMIT_EXCEEDED — the folder would hold more than 50 chats, FOLDER_CHAT_NOT_ELIGIBLE — the user is not a chat member or the chat type is not eligible. The response does not say which ID was refused
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a server error
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the im scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only — the call changes folder contents
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured

Full list of common API errors — Errors.

Known specifics

  • Adding a chat again does not duplicate it. Adding a chat that is already in the folder, or passing an ID twice or in both chatIds and dialogIds, returns success, and the folder still holds the chat only once.
  • A user ID in dialogIds creates a direct dialog if there is none yet.
  • dialogIds requires the im 26.1000.0 update or later. Cloud Bitrix24 already has it. A self-hosted Bitrix24 without it silently ignores dialogIds, so a request with only dialogIds succeeds without changing anything. On such an installation, pass chatIds.

See also