Для AI-агентов: markdown этой страницы — /docs-content/chats/members/list.md индекс документации — /llms.txt

Список участников

GET /v1/chats/:dialogId/users

Возвращает список участников диалога.

Параметры

Параметр Тип Обяз. По умолч. Описание
dialogId (path) string да — Идентификатор диалога: chatXXX для группового чата, ID пользователя для личного диалога с ним или алиас me для личного диалога с собой
limit (query) number нет 50 Количество участников, от 1 до 200. Значение вне диапазона срезается, эхо — meta.requestedLimit и meta.appliedLimit
offset (query) number нет 0 Смещение от начала списка. В режиме v2 отклоняется
lastId (query) number нет — ID последнего полученного участника — альтернатива offset для постраничного обхода. В режиме v2 отклоняется
skipExternal (query) boolean нет — true — исключить внешних пользователей (тип extranet, network). В режиме v2 отклоняется
format (query) string нет — v2 включает режим v2 — см. «Режим v2» ниже. Любое другое значение игнорируется, ответ прежний. Повтор format не отклоняется: из format=v1&format=v2 берётся последнее значение, то есть режим v2, а format=v2&format=v1 даёт прежний ответ. Форма format[]=v2 включает режим v2, если все её значения — v2
cursorRole (query) string нет — Только режим v2: data.nextCursor.role предыдущей страницы. Передаётся вместе с cursorRelationId
cursorRelationId (query) number нет — Только режим v2: data.nextCursor.relationId предыдущей страницы — страница начинается после этой записи участия. Передаётся вместе с cursorRole

Режим v2. format=v2 читает состав через мессенджер v2. В data приходят users — карточки участников, relations — записи участия с ролью owner, manager или member, и nextCursor — курсор следующей страницы; ключи в camelCase. Сначала идёт владелец, затем менеджеры, затем участники. Следующая страница — cursorRole и cursorRelationId из data.nextCursor. Полная страница всегда несёт курсор, поэтому список кончается страницей с nextCursor: null, и эта страница может быть пустой. Режим принимает только format, limit от 1 до 200 со срезанием и эхом и пару курсора; offset, lastId и skipExternal отклоняются с 400 INVALID_PARAMS. Режим v2 может сделать вас участником: если чат разрешает автовступление — например, чат комментариев, коллаб или чат задачи, — вызов добавляет текущего пользователя в участники, как загрузка чата. Режим v2 разрешён ключу READONLY по узкому исключению для автовступления; обычный режим также остаётся чтением. Сам вызов не отмечает сообщения прочитанными.

Примеры

curl — личный ключ

Terminal 
curl "https://vibecode.bitrix24.tech/v1/chats/chat123/users?limit=50" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal 
curl "https://vibecode.bitrix24.tech/v1/chats/chat123/users?limit=50" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/chat123/users?limit=50', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Участников:', data.length)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/chat123/users?limit=50', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()
console.log('Участников:', data.length)

curl — режим v2

Terminal 
curl "https://vibecode.bitrix24.tech/v1/chats/chat123/users?format=v2&limit=50&cursorRole=member&cursorRelationId=77" \
  -H "X-Api-Key: YOUR_API_KEY"

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data array Массив участников
data[].id number ID пользователя
data[].active boolean Активен ли аккаунт
data[].name string Полное имя
data[].firstName string Имя
data[].lastName string Фамилия
data[].workPosition string Должность
data[].color string Цвет аватара
data[].avatar string URL аватара (пустая строка, если аватар не задан)
data[].gender string Пол (M — мужской, F — женский, пустая строка — не указан)
data[].birthday string Дата рождения (пустая строка, если не указана)
data[].extranet boolean Внешний пользователь (тип extranet)
data[].network boolean Пользователь Bitrix24 Network
data[].bot boolean Бот
data[].connector boolean Пользователь открытых линий (Контакт-центр)
data[].status string Статус (online, away, dnd)
data[].idle boolean Неактивен
data[].lastActivityDate string Дата последней активности (ISO 8601)
data[].absent boolean Отсутствует по рабочему календарю
data[].departments number[] Список ID отделов
data[].type string Тип пользователя (user, bot, extranet)
data.users array Режим v2: карточки участников страницы — те же поля, что у элементов data[] обычного режима
data.relations array Режим v2: записи участия страницы
data.relations[].id number Режим v2: ID записи участия
data.relations[].userId number Режим v2: ID пользователя
data.relations[].chatId number Режим v2: ID чата
data.relations[].role string Режим v2: owner — владелец, manager — менеджер, member — участник
data.relations[].isHidden boolean Режим v2: скрытое участие
data.nextCursor object|null Режим v2: курсор следующей страницы — role и relationId; null — страниц больше нет
meta.requestedLimit number Переданный limit, когда он вышел за диапазон от 1 до 200
meta.appliedLimit number Применённое значение limit — только если он был приведён к границе

Пример ответа

Обычный режим:

JSON 
{
  "success": true,
  "data": [
    {
      "id": 42,
      "active": true,
      "name": "Иван Петров",
      "firstName": "Иван",
      "lastName": "Петров",
      "workPosition": "Менеджер",
      "color": "#df532d",
      "avatar": "",
      "gender": "M",
      "birthday": "",
      "extranet": false,
      "network": false,
      "bot": false,
      "connector": false,
      "status": "online",
      "idle": false,
      "lastActivityDate": "2026-06-05T09:40:32+03:00",
      "absent": false,
      "departments": [1, 47],
      "type": "user"
    },
    {
      "id": 53,
      "active": true,
      "name": "Мария Сидорова",
      "firstName": "Мария",
      "lastName": "Сидорова",
      "workPosition": "Аналитик",
      "color": "#83c3f7",
      "avatar": "",
      "gender": "F",
      "birthday": "",
      "extranet": false,
      "network": false,
      "bot": false,
      "connector": false,
      "status": "away",
      "idle": false,
      "lastActivityDate": "2026-06-04T18:15:00+03:00",
      "absent": false,
      "departments": [1],
      "type": "user"
    }
  ]
}

Режим v2, ответ на запрос «curl — режим v2» выше: страница после курсора последняя, поэтому nextCursor равен null. Карточки в users показаны сокращённо, полный набор полей — как в обычном режиме:

JSON 
{
  "success": true,
  "data": {
    "users": [
      { "id": 42, "active": true, "name": "Иван Петров", "firstName": "Иван", "lastName": "Петров", "type": "user" },
      { "id": 53, "active": true, "name": "Мария Сидорова", "firstName": "Мария", "lastName": "Сидорова", "type": "user" }
    ],
    "relations": [
      { "id": 81, "userId": 42, "chatId": 123, "isHidden": false, "role": "member" },
      { "id": 95, "userId": 53, "chatId": 123, "isHidden": false, "role": "member" }
    ],
    "nextCursor": null
  }
}

Пример ответа при ошибке

422 — ошибка Битрикс24 (нет доступа к диалогу):

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Access denied"
  }
}

Ошибки

HTTP Код Описание
400 INVALID_PARAMS Только режим v2: параметр вне format, limit, cursorRole, cursorRelationId, повтор параметра, кроме format, нечисловой limit, половина пары курсора без второй, роль вне owner, manager, member или cursorRelationId не положительное целое. Проверяется до обращения к Битрикс24
403 SCOPE_DENIED API-ключ не имеет скоупа im
401 TOKEN_MISSING API-ключ не имеет настроенных токенов Битрикс24
404 ENTITY_NOT_FOUND Режим v2: Битрикс24 вернул «не найдено»; код портала — в error.b24Code
422 BITRIX_ERROR Битрикс24 вернул ошибку — текст в поле message (например, нет доступа к диалогу). В режиме v2 код портала приходит в error.b24Code; отсутствующий чат — CHAT_NOT_FOUND
502 BITRIX_UNAVAILABLE Битрикс24 недоступен или вернул ошибку сервера
502 ME_ALIAS_RESOLUTION_FAILED Не удалось разрешить алиас me — токен истёк или недоступен Битрикс24

Полный список общих ошибок API — Ошибки.

Известные особенности

Пагинация через lastId. При последовательном обходе больших чатов передавайте lastId из последнего элемента предыдущего ответа вместо offset. Этот способ работает стабильнее при одновременных изменениях состава чата.

Алиас me возвращает участников личного диалога с собой — это вы один. Для состава группового чата передавайте chatXXX.

Смотрите также