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

Create a chat folder

POST /v1/chats/folders

Creates a personal chat folder for the current user and can populate it with chats right away.

To list folders with their id, call GET /v1/chats/folders.

Request fields (body)

Field Type Required Description
title string yes Folder name, 1 to 30 characters after trimming whitespace. A name outside these bounds is rejected with 422 BITRIX_ERROR, not 400
chatIds number[] no IDs of the chats in the initial contents. Each element is a positive integer: a number or a string of digits. The chat ID is the id field in recent dialogs
dialogIds string[] no Dialog IDs: chatXXX or a user ID for a direct dialog. An element is a non-empty string of up to 64 characters, with no commas and no leading or trailing whitespace. The me alias is not accepted — pass the user ID. The ID is the dialogId field in recent dialogs

The folder contents are the union of chatIds and dialogIds. There are no query parameters. Any query parameter or any other body field is rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
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": [5287], "dialogIds": ["chat5289"]}'

curl — OAuth application

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

JavaScript — personal key

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

const { success, data } = await res.json()
const folderId = data.folder.id

JavaScript — OAuth application

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

const { success, data } = await res.json()
const folderId = data.folder.id

Response fields

Field Type Description
success boolean Always true on success
data.folder object The created folder
data.folder.id number Folder ID
data.folder.type string Always personal
data.folder.title string Name
data.folder.sort number Folder position in the interface
data.folder.visible boolean The folder is shown in the interface
data.folder.description null A personal folder has no description
data.folder.displaysNestedInRoot boolean Nested chats are also shown in the root list
data.folder.definition.chats array Folder contents, a list of { chatId, dialogId }

Response example

JSON 
{
  "success": true,
  "data": {
    "folder": {
      "id": 127,
      "type": "personal",
      "title": "Clients",
      "sort": 12,
      "visible": true,
      "description": null,
      "displaysNestedInRoot": false,
      "definition": {
        "chats": [
          { "chatId": 5287, "dialogId": "chat5287" },
          { "chatId": 5289, "dialogId": "chat5289" }
        ]
      }
    }
  }
}

Error response example

422 — the name is longer than 30 characters:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "The string length must not exceed 30 characters",
    "b24Code": "title"
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS title is missing or is not a string, an element of chatIds or dialogIds is invalid, a query parameter or an unknown body field is passed, or the body is not a JSON object. Checked before any call to Bitrix24
422 BITRIX_ERROR Bitrix24 returned an error; the portal code is in error.b24Code: title — the name is empty after trimming whitespace or longer than 30 characters, FOLDER_LIMIT_EXCEEDED — the user already has 20 personal folders, FOLDER_CHATS_LIMIT_EXCEEDED — the contents exceed 50 chats, FOLDER_CHAT_NOT_ELIGIBLE — the contents include a chat that cannot be placed in a folder, for example a chat the user is not a member of
404 ENTITY_NOT_FOUND Bitrix24 returned "not found"; the portal code is in error.b24Code
403 SCOPE_DENIED The API key does not have the im scope
403 WRITE_BLOCKED_READONLY_KEY Read-only key: creating a folder is a write, see access rights
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable or returned a server error

The full list of common API errors — Errors.

Known specifics

  • A user ID in dialogIds creates a direct dialog. If there is no direct chat with the user yet, the call creates one and places it in the folder.
  • dialogIds works starting with the im 26.1000.0 update. Cloud Bitrix24 already has it installed. On-premise Bitrix24 without this update skips dialogIds and returns no error: a call with only dialogIds creates an empty folder. On such an installation, pass chatIds.
  • One ineligible chat rejects the whole contents. If the user is not a member of at least one chat in chatIds or dialogIds, the call returns FOLDER_CHAT_NOT_ELIGIBLE and the folder is not created, even when the other chats are eligible.

See also