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

Get a chat folder

GET /v1/chats/folders/:folderId

Returns one of the current user's folders. For a personal folder, it also returns the folder's chats and the users of the direct dialogs it contains.

The chats of a system folder are returned by GET /v1/chats/folders/:folderId/recent.

Parameters

Parameter Type Required Description
folderId (path) number yes Folder ID — the id field in GET /v1/chats/folders. A positive integer

The endpoint takes no query parameters: any query parameter is rejected with 400 INVALID_PARAMS.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/chats/folders/127" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

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

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/folders/127', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

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

JavaScript — OAuth application

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

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

Response fields

Field Type Description
success boolean Always true on success
data.folder object The folder
data.folder.id number Folder ID
data.folder.type string personal — a personal folder, system — a messenger section
data.folder.code string Messenger section code, for example default or tasksTask. Returned only for a system folder
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 string | null Section description for a system folder, null for a personal one
data.folder.displaysNestedInRoot boolean Nested chats are also shown in the root list
data.folder.definition object For a personal folder — its contents { chats: [{ chatId, dialogId }] }. For a system one — the list section: recentSection and parentChatId
data.chats array Chats of the personal folder in the v2 messenger format: id, dialogId, name, type, role, owner, permissions and other fields. An empty list for a system folder
data.users array Users of the direct dialogs in the folder. An empty list if the folder contains only group chats or is a system folder

Response example

A personal folder with one group chat:

JSON 
{
  "success": true,
  "data": {
    "chats": [
      {
        "avatar": "",
        "color": "#4ba984",
        "description": "",
        "dialogId": "chat5287",
        "diskFolderId": 0,
        "entityData1": "",
        "entityData2": "",
        "entityData3": "",
        "entityId": "",
        "entityType": "",
        "extranet": false,
        "containsCollaber": false,
        "id": 5287,
        "parentChatId": 0,
        "parentMessageId": 0,
        "name": "Docs check",
        "owner": 1,
        "messageType": "C",
        "role": "owner",
        "muteList": [],
        "type": "chat",
        "entityLink": { "type": "", "url": "", "id": "" },
        "permissions": {
          "manageUsersAdd": "member",
          "manageUsersDelete": "manager",
          "manageUi": "member",
          "manageSettings": "owner",
          "manageMessages": "member",
          "manageMessagesAutoDelete": "manager",
          "manageGuestInvites": "manager",
          "manageDelete": "member",
          "canPost": "member"
        },
        "hasManageCapability": false,
        "isNew": false,
        "textFieldEnabled": true,
        "backgroundId": null,
        "canHaveThreads": true
      }
    ],
    "users": [],
    "folder": {
      "id": 127,
      "type": "personal",
      "title": "Key clients",
      "sort": 12,
      "visible": true,
      "description": null,
      "displaysNestedInRoot": false,
      "definition": {
        "chats": [{ "chatId": 5287, "dialogId": "chat5287" }]
      }
    }
  }
}

A system folder — the lists are empty:

JSON 
{
  "success": true,
  "data": {
    "chats": [],
    "users": [],
    "folder": {
      "id": 27,
      "type": "system",
      "code": "default",
      "title": "Chats",
      "sort": 2,
      "visible": true,
      "description": "All chats, channels and projects",
      "displaysNestedInRoot": false,
      "definition": { "recentSection": "default", "parentChatId": 0 }
    }
  }
}

Error response example

422 — no folder with this folderId:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "FOLDER_NOT_FOUND",
    "b24Code": "FOLDER_NOT_FOUND"
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS folderId is not a positive integer, or a query parameter was passed. Checked before any call to Bitrix24
422 BITRIX_ERROR Bitrix24 returned an error; the portal code is in error.b24Code: FOLDER_NOT_FOUND — no such folder, FOLDER_ACCESS_DENIED — another user's folder
404 ENTITY_NOT_FOUND Bitrix24 answered "not found"; the portal code is in error.b24Code
403 SCOPE_DENIED The API key does not have the im scope
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable or returned a server error

Full list of common API errors — Errors.

Known specifics

  • A read-only key can make the call. The call's argument is a folder, not a chat, so reading a folder does not make the user a member of its chats and does not count as a write. The folder list GET /v1/chats/folders returns 403 WRITE_BLOCKED_READONLY_KEY to such a key, so get the folderId with a key that has write access.
  • 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