## Операторы (real-time)

> ⚠️ **Метод выходит в обновлении `imopenlines 26.700.0` и доступен пока не на всех порталах Битрикс24.** Если обновление на ваш портал ещё не пришло, API вернёт `422 METHOD_NOT_YET_AVAILABLE` — это признак того, что метод на портале ещё не выпущен, а не ошибка интеграции.

`GET /v1/openlines/operators`

Список операторов линии с текущим статусом и нагрузкой — для real-time виджетов мониторинга контакт-центра.

Данные почти real-time: статус и счётчик активных сессий читаются раздельно, без единой транзакции. Для виджета опрашивайте метод не чаще одного раза в 30 секунд.

## Поля запроса (query)

| Параметр | Тип | Обяз. | Описание |
|------|-----|:-----:|---------|
| `configId` | number | нет | Идентификатор линии. Источник: [`GET /v1/openline-configs`](/docs/openlines/config/list) |
| `configIdList` | number[] | нет | Список линий. Форма — `configIdList=3,5` или `configIdList[]=3&configIdList[]=5` |
| `userId` | number | нет | Идентификатор оператора. Источник: [`GET /v1/users`](/docs/entities/users) |
| `userIdList` | number[] | нет | Список операторов, те же две формы |
| `status` | string | нет | Статус: `online`, `offline` или `pause` |
| `hasFreeSlots` | boolean | нет | Только операторы со свободными слотами. Принимает `true`/`false` и `Y`/`N` |
| `limit` | number | нет | Размер страницы, 1..200 (по умолчанию 50) |
| `offset` | number | нет | Смещение для пагинации (по умолчанию 0) |

Списочные параметры принимают либо строку через запятую (`configIdList=3,5`), либо повторяющуюся скобочную форму (`configIdList[]=3&configIdList[]=5`). Голое повторение параметра без скобок (`configIdList=3&configIdList=5`) не поддерживается.

## Примеры

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

```bash
curl "https://vibecode.bitrix24.tech/v1/openlines/operators?configId=3&status=online" \
  -H "X-Api-Key: YOUR_API_KEY"
```

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

```bash
curl "https://vibecode.bitrix24.tech/v1/openlines/operators?configId=3&status=online" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/openlines/operators?configId=3&status=online', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
```

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

```javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/openlines/operators?configId=3&status=online', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()
```

## Поля ответа

Ответ — `{ "success": true, "data": { "operators": [...], "hasNextPage": bool } }`.

| Ключ | Описание |
|---|---|
| `operators` | Массив операторов |
| `operators[].userId` | Идентификатор пользователя-оператора |
| `operators[].configId` | Идентификатор линии |
| `operators[].status` | Статус: `online` / `offline` / `pause` |
| `operators[].activeSessions` | Количество активных (незакрытых) сессий прямо сейчас |
| `operators[].maxChat` | Лимит чатов оператора (из настроек линии) |
| `operators[].freeSlots` | Свободные слоты (`maxChat − activeSessions`) |
| `operators[].lastActivityDate` | Дата последней активности оператора в линии |
| `hasNextPage` | Есть ли следующая страница |

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

```json
{
  "success": true,
  "data": {
    "operators": [
      { "userId": 42, "configId": 3, "status": "online", "activeSessions": 2, "maxChat": 5, "freeSlots": 3, "lastActivityDate": "2026-06-15T15:01:00+03:00" },
      { "userId": 51, "configId": 3, "status": "pause", "activeSessions": 0, "maxChat": 5, "freeSlots": 5, "lastActivityDate": "2026-06-15T14:20:00+03:00" }
    ],
    "hasNextPage": false
  }
}
```

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

`422` — недопустимое значение `status` (значение уходит в Битрикс24, тот отклоняет фильтр):

```json
{
  "success": false,
  "error": { "code": "BITRIX_ERROR", "message": "Недопустимое значение фильтра", "b24Code": "INVALID_FILTER" }
}
```

## Ошибки

| HTTP | Код | Когда |
|---|---|---|
| 403 | `B24_TARIFF_RESTRICTION` | Тариф не включает статистику Открытых линий (`report_open_lines`) |
| 400 | `INVALID_PARAMS` | Нечисловое значение в `limit`/`offset` или элементе списка |
| 422 | `BITRIX_ERROR` (`error.b24Code: INVALID_FILTER`) | Недопустимое значение `status` |
| 422 | `BITRIX_ERROR` (`error.b24Code: OFFSET_TOO_LARGE`) | `offset` превышает максимум при фильтре `status`/`hasFreeSlots` — сузьте фильтры |
| 422 | `METHOD_NOT_YET_AVAILABLE` | Обновление `imopenlines 26.700.0` ещё не приехало на портал |

Полный список системных кодов — [Ошибки API](/docs/errors).

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

- [Агрегаты по линии за период](/docs/openlines/stats)
- [Статистика Открытых линий](/docs/openlines)