Folder contents

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

DELETE /v1/chats/folders/:folderId/chats

PUT /v1/chats/:dialogId/folders

Sorts chats into the current user's personal folders — from both sides:

• POST /v1/chats/folders/:folderId/chats adds chats to a folder — the v2 messenger method im.v2.Folder.addChats.
• DELETE /v1/chats/folders/:folderId/chats removes chats from a folder — the method im.v2.Folder.deleteChats.
• PUT /v1/chats/:dialogId/folders sets the full set of personal folders of one chat — the method im.v2.Folder.setChatFolders.

Do not confuse with GET /v1/chats/:chatId/folder — that is the chat's Drive folder, not a chat-list folder.

All three calls are writes: a read-only key gets 403 WRITE_BLOCKED_READONLY_KEY before any call to Bitrix24. To create a folder and replace its contents as a whole, see Chat folders: create and edit.

Parameters

POST and DELETE require at least one ID in chatIds or dialogIds. For DELETE the lists are passed only in the query: the body of a DELETE is not read.

Each element of chatIds and folderIds is a positive integer: a number or a string of digits. An element of dialogIds is a non-empty string of up to 64 characters without commas. The me alias is not accepted in the lists — pass the user ID. Any other query parameter or body field is rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

# Add two chats to folder 16
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"]}'

# Remove a chat from folder 16
curl -X DELETE "https://vibecode.bitrix24.com/v1/chats/folders/16/chats?chatIds=42" \
  -H "X-Api-Key: YOUR_API_KEY"

# Chat chat42 — only in folders 15 and 16
curl -X PUT "https://vibecode.bitrix24.com/v1/chats/chat42/folders" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"folderIds": [15, 16]}'

curl — OAuth application

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]}'

JavaScript — personal key

// Remove a chat from all personal folders
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/chat42/folders', {
  method: 'PUT',
  headers: { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ folderIds: [] }),
})

const { success } = await res.json()

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/chats/folders/16/chats?dialogIds=chat42,7', {
  method: 'DELETE',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success } = await res.json()

Response fields

Response example

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

Error response example

400 — PUT without folderIds:

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`folderIds` is missing: pass the full list of the personal folders of the chat (`[]` takes it out of all of them)."
  }
}

422 — the chat cannot be put into a folder:

{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "This chat cannot be added to the folder.",
    "b24Code": "FOLDER_CHAT_NOT_ELIGIBLE"
  }
}

Errors

Full list of common API errors — Errors.

Known specifics

• PUT sets the full set. The chat ends up exactly in the listed personal folders and disappears from the others. That is why folderIds is required: without it Bitrix24 would remove the chat from all folders. Bitrix24 silently skips IDs of system folders and of other users' folders.
• PUT can make the key owner a chat member. If the chat allows auto-join — for example, a comment chat, a collab or a task chat — the call adds the key owner as a member, as opening the chat in the Bitrix24 interface does.
• A user ID in dialogIds for POST creates a direct dialog if there is none yet. DELETE creates no dialog.
• 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 POST or DELETE with only dialogIds succeeds without changing anything. On such an installation, pass chatIds.
• Bitrix24 checks whether a chat can be put into a folder: the user must be a chat member, and the chat itself must be of a suitable type. The refusal arrives with the code FOLDER_CHAT_NOT_ELIGIBLE; the response does not say which IDs were refused.
• POST and DELETE without a single ID are rejected with 400: Bitrix24 would answer with success and change nothing.

See also

• Chat folders: create and edit
• Chat folders
• Folder chats
• Chat management