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
folderId (path) number yes Personal folder ID — the id of a folder with type: "personal" from GET /v1/chats/folders

Request fields (body)

Field Type Required Description
chatIds number[] no Chat IDs — the chatId field of recent dialogs. Each element is a positive integer: a number or a string of digits without leading zeros
dialogIds string[] no Dialog 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
success boolean Always true on success
data.result boolean true — 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
400 INVALID_PARAMS folderId 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
404 ENTITY_NOT_FOUND Bitrix24 answered "not found"; the portal code is in error.b24Code
422 BITRIX_ERROR Bitrix24 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
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable or returned a server error
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 folder contents
401 TOKEN_MISSING The 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