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

Участники

Просматривайте состав чата, кандидатов для упоминания и связи участников, добавляйте и удаляйте участников, назначайте менеджеров.

Скоуп: im | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key

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

GET /v1/chats/:dialogId/users

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

Общий параметр filter этим эндпоинтом не применяется. По умолчанию API сохраняет прежний ответ HTTP 200 и прежние данные, добавляет заголовок Warning: 299 - "filter is not supported on this endpoint and was ignored", а сервер фиксирует использование неподдерживаемого фильтра в журнале. Проверка параметров для format=v2 сохраняется без изменений.

Параметры

Параметр Тип Обяз. По умолч. Описание
Параметр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 может сделать вас участником: если чат разрешает автовступление — например, чат комментариев, коллаб или чат задачи, — вызов добавляет текущего пользователя в участники, как загрузка чата. Ключу READONLY режим v2 разрешён при двух условиях: это личный ключ сотрудника, и чат подтверждён — передан chatN или личный диалог найден в последних диалогах того же сотрудника. Обычный режим остаётся чтением без этих условий. Сам вызов не отмечает сообщения прочитанными.

Примеры

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 Код Описание
HTTP200 КодWarning: 299 ОписаниеФильтр игнорируется по умолчанию; прежние данные сохраняются, предупреждение передаётся заголовком Warning.
HTTP400 только при включённом строгом режиме КодUNSUPPORTED_FILTER ОписаниеСерверный режим выключен по умолчанию; до его включения эндпоинт сохраняет HTTP 200 и прежние данные.
HTTP400 КодINVALID_PARAMS ОписаниеТолько режим v2: параметр вне format, limit, cursorRole, cursorRelationId, повтор параметра, кроме format, нечисловой limit, половина пары курсора без второй, роль вне owner, manager, member или cursorRelationId не положительное целое. Проверяется до обращения к Битрикс24
HTTP403 КодSCOPE_DENIED ОписаниеAPI-ключ не имеет скоупа im
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеРежим v2: ключ только для чтения, а чат не подтверждён — передан не chatN, и личный диалог не найден в списке последних диалогов того же сотрудника, до 20 страниц и 4000 строк, либо алиас создаёт диалог. Отказ приходит до обращения к Битрикс24
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеРежим v2: ключ только для чтения, и это не личный ключ сотрудника — ключ приложения с сессией пользователя, менеджмент-ключ или ключ с неподтверждённым владельцем
HTTP401 КодTOKEN_MISSING ОписаниеAPI-ключ не имеет настроенных токенов Битрикс24
HTTP404 КодENTITY_NOT_FOUND ОписаниеРежим v2: Битрикс24 вернул «не найдено». Код портала — в error.b24Code
HTTP422 КодBITRIX_ERROR ОписаниеБитрикс24 вернул ошибку — текст в поле message, например при отсутствии доступа к диалогу. В режиме v2 код портала приходит в error.b24Code, отсутствующий чат — CHAT_NOT_FOUND
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеБитрикс24 недоступен или вернул ошибку сервера
HTTP502 КодME_ALIAS_RESOLUTION_FAILED ОписаниеНе удалось разрешить алиас me — токен истёк или недоступен Битрикс24

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

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

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

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

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