Участники рабочей группы

GET /v1/workgroups/:groupId/users

Возвращает участников рабочей группы вместе с их ролью в ней — владелец, модератор или участник.

Параметры

Параметров постраничной выдачи у операции нет: состав возвращается целиком.

Примеры

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

curl "https://vibecode.bitrix24.tech/v1/workgroups/85/users" \
  -H "X-Api-Key: YOUR_API_KEY"

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

curl "https://vibecode.bitrix24.tech/v1/workgroups/85/users" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

const res = await fetch('https://vibecode.bitrix24.tech/v1/workgroups/85/users', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
const moderators = data.filter(m => m.role === 'A' || m.role === 'E')
console.log('Руководителей и модераторов:', moderators.length)

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

const res = await fetch('https://vibecode.bitrix24.tech/v1/workgroups/85/users', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Поля ответа

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

{
  "success": true,
  "data": [
    { "userId": 1269, "role": "A" },
    { "userId": 1271, "role": "E" },
    { "userId": 779, "role": "K" }
  ],
  "meta": {
    "total": 3
  }
}

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

404 — группы с таким groupId нет либо она не видна этому ключу:

{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Workgroup not found, or not visible to the identity this key acts as"
  }
}

Ошибки

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

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

• Роль приходит буквой Битрикс24 как есть. Незнакомая буква проходит насквозь, а не приводится к известной и не отбрасывается: так контракт переживёт появление новой роли. Проверяйте те значения, которые знаете, а всё остальное трактуйте как отсутствие прав — не подставляйте «участник» по умолчанию.
• Владелец группы не обязательно есть среди строк. Его идентификатор отдаёт поле ownerId в GET /v1/workgroups/:id; выводить владельца из наличия строки с ролью A нельзя.
• Пустой состав — обычный ответ, а не ошибка. У существующей группы участников может не быть вовсе, тогда приходит 200 с пустым data.
• 404 не означает «группы не существует». Битрикс24 одинаково отказывает и для несуществующей, и для невидимой этому ключу группы, поэтому различить их на стороне API невозможно.
• Это данные о составе, а не решение о доступе. Что именно покажет эндпоинт, зависит от личности за ключом: личный ключ и вебхук читают от имени своего владельца, а OAuth-ключ с проброшенной пользовательской сессией — от имени этого пользователя. Признак администратора портала сюда не входит: его отдаёт GET /v1/users/me. Гейт «руководитель, модератор или админ портала» собирается из двух источников.
• Нечисловой или дробный groupId возвращает 400, а не данные другой группы. Битрикс24 округляет такой идентификатор вниз и ответил бы составом другой группы — платформа отбивает такой запрос до вызова.
• Постраничной выдачи нет: limit и offset не принимаются и игнорируются, состав возвращается целиком, meta.total всегда равен длине data.
• meta.warnings появляется только в двух случаях: DUPLICATE_MEMBER_ROW — Битрикс24 вернул больше одной строки на одного пользователя (строки отдаются как есть; если роли в них расходятся, считайте членство неоднозначным), и MEMBER_ROSTER_PAGE_BOUNDARY — вернулось ровно 50 строк, что неотличимо от усечённой первой страницы; сверьте с полем membersCount в GET /v1/workgroups/:id, если важен точный состав.
• Через POST /v1/batch операция недоступна — вложенные ресурсы там не адресуются.

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

• Получить рабочую группу
• Список рабочих групп
• Поля рабочей группы