Chat folders: create and edit

POST /v1/chats/folders

GET /v1/chats/folders/:folderId

PATCH /v1/chats/folders/:folderId

DELETE /v1/chats/folders/:folderId

PUT /v1/chats/folders/order

Creates, reads, edits and deletes the current user's personal chat folders and sets the order of all their folders — the v2 messenger methods im.v2.Folder.add, im.v2.Folder.get, im.v2.Folder.update, im.v2.Folder.delete and im.v2.Folder.sort. The folder list with each folder's id and type is GET /v1/chats/folders; a folder's chats in the order of the recent dialog list are GET /v1/chats/folders/:folderId/recent. To add and remove individual chats, see Folder contents.

• POST /v1/chats/folders creates a personal folder and can fill it with chats right away.
• GET /v1/chats/folders/:folderId returns the folder with its chats and their users.
• PATCH /v1/chats/folders/:folderId renames a personal folder and replaces its contents.
• DELETE /v1/chats/folders/:folderId permanently deletes a personal folder together with its contents and pins. The chats themselves stay.
• PUT /v1/chats/folders/order sets the order of the folders in the interface.

All calls except GET are writes: a read-only key gets 403 WRITE_BLOCKED_READONLY_KEY before any call to Bitrix24. System folders — the messenger's sections — cannot be created, renamed or deleted.

Parameters

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.

PATCH needs at least one of title, chatIds, dialogIds. Empty contents — chatIds: [], dialogIds: [] or both — clear the folder. There are no query parameters. Any other query parameter or body field is rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

# Create a folder with two chats
curl -X POST "https://vibecode.bitrix24.com/v1/chats/folders" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Clients", "chatIds": [42], "dialogIds": ["chat57"]}'

# Rename a folder
curl -X PATCH "https://vibecode.bitrix24.com/v1/chats/folders/16" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Key clients"}'

# Put a folder first
curl -X PUT "https://vibecode.bitrix24.com/v1/chats/folders/order" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"folderIds": [16, 1, 2, 4, 5, 6]}'

curl — OAuth application

curl "https://vibecode.bitrix24.com/v1/chats/folders/16" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

const headers = { 'X-Api-Key': 'YOUR_API_KEY', 'Content-Type': 'application/json' }

const created = await fetch('https://vibecode.bitrix24.com/v1/chats/folders', {
  method: 'POST',
  headers,
  body: JSON.stringify({ title: 'Clients', chatIds: [42] }),
}).then((r) => r.json())

const folderId = created.data.folder.id

// Clear the folder: empty contents
await fetch(`https://vibecode.bitrix24.com/v1/chats/folders/${folderId}`, {
  method: 'PATCH',
  headers,
  body: JSON.stringify({ chatIds: [] }),
})

JavaScript — OAuth application

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

const { success } = await res.json()

Response fields

POST and PATCH:

GET:

DELETE and PUT …/order:

Response example

POST:

{
  "success": true,
  "data": {
    "folder": {
      "id": 16,
      "type": "personal",
      "title": "Clients",
      "sort": 13,
      "visible": true,
      "description": null,
      "displaysNestedInRoot": false,
      "definition": { "chats": [{ "chatId": 42, "dialogId": "chat42" }] }
    }
  }
}

DELETE:

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

Error response example

400 — PATCH without fields:

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Nothing to change: pass `title`, `chatIds` or `dialogIds`."
  }
}

422 — a name longer than 30 characters:

{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "String must not be longer than 30 characters.",
    "b24Code": "title"
  }
}

Errors

Full list of common API errors — Errors.

Known specifics

• Empty contents clear the folder. Bitrix24 itself reads an empty list as "field not passed", so PATCH sends Bitrix24 its clearing value instead. The contents you pass always replace the previous ones completely: to add or remove one chat, use Folder contents.
• A user ID in dialogIds creates a direct dialog. If there is no direct chat with the user yet, POST and PATCH create it and put it into the folder.
• dialogIds requires the im 26.1000.0 update or later. Cloud Bitrix24 already has it. A self-hosted Bitrix24 without it silently ignores dialogIds: a POST with only dialogIds creates an empty folder, and a PATCH leaves the contents unchanged. On such an installation, pass chatIds.
• Bitrix24 removes a chat the user is no longer a member of. When the contents are written, such a chat silently drops out of the folder. Check data.folder.definition.chats in the response.
• PUT …/order accepts only the full set. Pass all visible folders, system and personal, otherwise Bitrix24 returns FOLDER_SORT_INVALID. Bitrix24 recalculates the sort values itself, so after the call they may differ from the previous values even if the order is unchanged.
• GET only reads: its argument is a folder, not a chat, so a read-only key can call it.
• The limits are Bitrix24 rules: 20 personal folders, 50 chats in a folder, a name of up to 30 characters. Bitrix24 checks them, and the refusal code arrives in error.b24Code.
• The code FOLDER_NOT_FOUND arrives in error.b24Code of a 422 BITRIX_ERROR response. Do not confuse it with 404 FOLDER_NOT_FOUND of the chat's Drive folder.

See also

• Chat folders
• Folder contents
• Sources of the "All" folder
• Folder chats