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

Update a chat folder

PATCH /v1/chats/folders/:folderId

Renames the current user's personal chat folder and replaces its contents.

To add or remove individual chats without passing the full contents, see Add chats to a folder and Remove chats from a folder.

Parameters

Parameter Type Required Description
ParameterfolderId (path) Typenumber Requiredyes DescriptionPersonal folder ID — the id field in GET /v1/chats/folders. A positive integer

There are no query parameters: any query parameter is rejected with 400 INVALID_PARAMS.

Request fields (body)

Field Type Required Description
Fieldtitle Typestring Requiredno DescriptionNew folder name, 1 to 30 characters after trimming whitespace. A name outside these bounds is rejected with 422 BITRIX_ERROR, not 400
FieldchatIds Typenumber[] Requiredno DescriptionChat IDs of the new 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 of the new contents: 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

At least one of title, chatIds, dialogIds is required. The passed contents — the union of chatIds and dialogIds — replace the previous contents entirely. Empty contents — chatIds: [], dialogIds: [] or both — clear the folder. Any other body field is rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl -X PATCH "https://vibecode.bitrix24.com/v1/chats/folders/127" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Key clients", "chatIds": [5287]}'

curl — OAuth application

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

JavaScript — personal key

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

const { success, data } = await res.json()
console.log(data.folder.definition.chats)

JavaScript — OAuth application

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

const { success, data } = await res.json()
console.log(data.folder.definition.chats)

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.folder Typeobject DescriptionThe folder after the update
Fielddata.folder.id Typenumber DescriptionFolder ID
Fielddata.folder.type Typestring DescriptionAlways personal
Fielddata.folder.title Typestring DescriptionName
Fielddata.folder.sort Typenumber DescriptionFolder order 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 after the update, a list of { chatId, dialogId }

Response example

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

Error response example

400 — no field passed:

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

Errors

HTTP Code Description
HTTP400 CodeINVALID_PARAMS DescriptionfolderId is not a positive integer, no field passed, title is not a string, an invalid chatIds or dialogIds element, 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 FOLDER_NOT_FOUND — the folder does not exist. The portal code is in error.b24Code
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned FOLDER_ACCESS_DENIED — the folder belongs to another user. The portal code is in error.b24Code
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned FOLDER_SYSTEM_MUTATION_FORBIDDEN — a system folder cannot be changed. The portal code is in error.b24Code
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned FOLDER_CHATS_LIMIT_EXCEEDED — the contents exceed 50 chats. The portal code is in error.b24Code
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned 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. The portal code is in error.b24Code
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned title — the name is empty after trimming whitespace or longer than 30 characters. The portal code is in error.b24Code
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: updating 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

For the full list of common API errors, see Errors.

Known specifics

  • 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 previous contents remain, even when the other chats are eligible.
  • A user ID in dialogIds creates a direct dialog. If there is no direct chat with the user yet, the call creates it 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 does not change the contents. On such an installation, pass chatIds.
  • FOLDER_NOT_FOUND arrives in error.b24Code of a 422 BITRIX_ERROR response. Do not confuse it with the 404 FOLDER_NOT_FOUND on Upload a file to a chat.

See also