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

GET /v1/chats/:dialogId/users

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

#Параметры

Параметр Тип Обяз. По умолч. Описание
dialogId (path) string да — Идентификатор диалога (chatXXX) или алиас me для личного диалога с собой
limit (query) number нет 50 Количество участников (1–200)
offset (query) number нет 0 Смещение от начала списка
lastId (query) number нет — ID последнего полученного участника — альтернатива offset для постраничного обхода
skipExternal (query) boolean нет — true — исключить внешних пользователей (тип extranet, network)

#Примеры

#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)

#Поля ответа

Поле Тип Описание
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)

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

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"
    }
  ]
}

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

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

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

#Ошибки

HTTP Код Описание
403 SCOPE_DENIED API-ключ не имеет скоупа im
401 TOKEN_MISSING API-ключ не имеет настроенных токенов Битрикс24
422 BITRIX_ERROR Битрикс24 вернул ошибку — текст в поле message (например, нет доступа к диалогу)
502 BITRIX_UNAVAILABLE Битрикс24 недоступен или вернул ошибку сервера
502 ME_ALIAS_RESOLUTION_FAILED Не удалось разрешить алиас me — токен истёк или недоступен Битрикс24

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

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

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

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

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