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

Активные участники

GET /v1/chats/:dialogId/users/active

Возвращает участников чата карточками пользователей, одной страницей и с выбранной сортировкой. Самые активные собеседники — sort=lastSendMessageId&order=desc. Весь состав постранично отдаёт список участников в режиме v2.

Параметры

Параметр Тип Обяз. По умолч. Описание
dialogId (path) string да — Идентификатор диалога: chatXXX для группового чата, ID пользователя для личного диалога с ним или алиас me для личного диалога с собой
limit (query) number нет 50 Сколько участников вернуть, от 1 до 200. Значение вне диапазона срезается, эхо — meta.requestedLimit и meta.appliedLimit
sort (query) string нет — Ключ сортировки: id — запись участия, lastSendMessageId — последнее сообщение участника, userId — ID пользователя. Без sort порядок определяет Битрикс24
order (query) string нет desc Направление sort: desc или asc, регистр не важен. Только вместе с sort

Другие параметры и повторы отклоняются с 400 INVALID_PARAMS.

Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/chats/chat42/users/active?sort=lastSendMessageId&order=desc&limit=10" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/chats/chat42/users/active?sort=lastSendMessageId&order=desc&limit=10" \
  -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/chat42/users/active?sort=lastSendMessageId&order=desc&limit=10', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

const { data } = await res.json()
console.log('Активные:', data.map((u) => u.name))

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/chat42/users/active?sort=lastSendMessageId&order=desc&limit=10', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { data } = await res.json()
console.log('Активные:', data.map((u) => u.name))

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data array Карточки участников — те же поля, что в списке участников
data[].id number ID пользователя
data[].active boolean Активен ли аккаунт
data[].name string Полное имя
data[].firstName string Имя
data[].lastName string Фамилия
data[].workPosition string|null Должность
data[].color string Цвет аватара
data[].avatar string URL аватара. Пустая строка, если аватар не задан
data[].gender string Пол: M — мужской, F — женский, пустая строка — не указан
data[].birthday string Дата рождения. Пустая строка, если не указана
data[].extranet boolean Внешний пользователь, тип extranet
data[].network boolean Пользователь Битрикс24.Network
data[].connector boolean Пользователь открытых линий Контакт-центра
data[].idle boolean Неактивен
data[].absent boolean | string false или дата окончания отсутствия
data[].departments number[] ID отделов пользователя. Список: GET /v1/departments
data[].status string Статус (online, away, dnd)
data[].lastActivityDate string Дата последней активности (ISO 8601)
data[].bot boolean Бот
data[].type string Тип пользователя (user, bot, extranet)
meta.requestedLimit number Переданный limit, когда он вышел за диапазон от 1 до 200
meta.appliedLimit number Применённое значение limit — только если он был приведён к границе

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

JSON 
{
  "success": true,
  "data": [
    {
      "id": 7,
      "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-09-20T10:00:00+03:00",
      "absent": false,
      "departments": [1],
      "type": "user"
    }
  ]
}

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

400 — order без sort:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`order` sets the direction of `sort` and is accepted only together with it."
  }
}

Ошибки

HTTP Код Описание
400 INVALID_PARAMS Параметр вне limit, sort, order, повтор параметра, нечисловой limit, sort или order вне списка, order без sort. Проверяется до обращения к Битрикс24
403 SCOPE_DENIED API-ключ не имеет скоупа im
403 WRITE_BLOCKED_READONLY_KEY Ключ только для чтения, а чат не подтверждён: передан не chatN, и личный диалог не найден в списке последних диалогов того же сотрудника — до 20 страниц и 4000 строк, — либо алиас создаёт диалог. Отказ приходит до обращения к Битрикс24
403 WRITE_BLOCKED_READONLY_KEY Ключ только для чтения, и это не личный ключ сотрудника: ключ приложения с сессией пользователя, менеджмент-ключ или ключ с неподтверждённым владельцем
401 TOKEN_MISSING API-ключ не имеет настроенных токенов Битрикс24
404 ENTITY_NOT_FOUND Битрикс24 вернул «не найдено»; код портала — в error.b24Code
422 BITRIX_ERROR Битрикс24 вернул ошибку; код портала — в error.b24Code. Отсутствующий чат приходит сюда с кодом CHAT_NOT_FOUND
502 ME_ALIAS_RESOLUTION_FAILED Не удалось определить пользователя при использовании алиаса me

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

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

Чтение может сделать вас участником. Если чат разрешает автовступление, Битрикс24 может добавить текущего пользователя в участники. Ключу READONLY это чтение разрешено по узкому исключению; оно не отмечает сообщения прочитанными. Права пользователя в Битрикс24 и скоуп im сохраняются.

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