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
Fieldtitle Typestring Requiredyes DescriptionFolder name, 1 to 30 characters after trimming whitespace. A name outside these bounds is rejected with 422 BITRIX_ERROR, not 400
FieldchatIds Typenumber[] Requiredno DescriptionIDs 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
FielddialogIds Typestring[] Requiredno DescriptionDialog 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.folder Typeobject DescriptionThe created folder
Fielddata.folder.id Typenumber DescriptionFolder ID
Fielddata.folder.type Typestring DescriptionAlways personal
Fielddata.folder.title Typestring DescriptionName
Fielddata.folder.sort Typenumber DescriptionFolder position in the interface
Fielddata.folder.visible Typeboolean DescriptionThe folder is shown in the interface
Fielddata.folder.description Typenull DescriptionA personal folder has no description
Fielddata.folder.displaysNestedInRoot Typeboolean DescriptionNested chats are also shown in the root list
Fielddata.folder.definition.chats Typearray DescriptionFolder 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
HTTP400 CodeINVALID_PARAMS Descriptiontitle 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
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 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
HTTP404 CodeENTITY_NOT_FOUND DescriptionBitrix24 returned "not found"; the portal code is in error.b24Code
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the im scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionRead-only key: creating a folder is a write, see access rights
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 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