# Открытые линии

Открытые линии Битрикс24 (модуль `imopenlines`) — входящие обращения из мессенджеров и социальных сетей, распределение по операторам, интеграция с CRM и оценка качества обслуживания. Раздел покрывает две грани модуля: управление настройками линий и статистику дашборда руководителя контакт-центра.

- **Базовый URL:** `https://vibecode.bitrix24.tech`
- **Аутентификация:** заголовок `X-Api-Key` (личный ключ) или `X-Api-Key` + `Authorization: Bearer` (OAuth-приложение)
- **Скоуп ключа:** `imopenlines`

## Что входит в раздел

| Грань | Назначение | Документация |
|---|---|---|
| Конфигурация линий | CRUD настроек линии: очередь операторов, рабочее время, интеграция с CRM, приветствие, оценка | [Конфигурация линий](/docs/openlines/config) |
| Статистика (дашборд) | Только чтение: агрегаты, сессии, операторы, CSAT, переназначения | ниже в этом разделе |

## Идентификаторы

| Идентификатор | Что это | Где взять |
|---|---|---|
| `configId` | Открытая линия | [`GET /v1/openline-configs`](/docs/openlines/config/list) |
| `sessionId` | Сессия (диалог) Открытой линии | [`POST /v1/openlines/sessions/search`](/docs/openlines/sessions) |
| `chatId` | IM-чат, привязанный к сессии | поле `chatId` в ответе `sessions/search` |

## Конфигурация линий

Управление настройками открытых линий — создание, список, получение, изменение, удаление, поиск. Общедоступно, раскатки обновления не требует. Здесь же живут два действия оператора над диалогом — принять (`answer`) и завершить (`finish`).

Полная документация: [Конфигурация линий](/docs/openlines/config).

## Статистика (дашборд)

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

Список обращений с метриками, real-time нагрузка операторов, агрегаты по линии, оценки клиентов (CSAT) и история переназначений. Все методы — только чтение. Данные видны в пределах прав пользователя, от имени которого работает ключ: если у него нет доступа ни к одной линии, метод возвращает пустой результат (или нулевые агрегаты), а не ошибку. Методам нужен доступ к статистике Открытых линий (право `report_open_lines`); без него запрос вернёт `403 B24_TARIFF_RESTRICTION`.

| Эндпоинт | Метод Битрикс24 | Назначение |
|---|---|---|
| [`POST /v1/openlines/stats`](/docs/openlines/stats) | `imopenlines.v2.Stat.get` | Агрегаты по линии за период |
| [`GET /v1/openlines/operators`](/docs/openlines/operators) | `imopenlines.v2.Operator.list` | Операторы: статус и нагрузка (real-time) |
| [`POST /v1/openlines/sessions/search`](/docs/openlines/sessions) | `imopenlines.v2.Session.list` | Список сессий с фильтрами |
| [`POST /v1/openlines/sessions/stats`](/docs/openlines/sessions/stats) | `imopenlines.v2.Session.Stat.get` | Метрики по конкретным сессиям (до 100) |
| [`POST /v1/openlines/ratings/search`](/docs/openlines/ratings) | `imopenlines.v2.Session.Rating.list` | Оценённые сессии (CSAT) за период |
| [`POST /v1/openlines/sessions/transfers`](/docs/openlines/sessions/transfers) | `imopenlines.v2.Session.Transfer.list` | История переназначений (до 50 сессий) |

Все шесть методов выходят в обновлении `imopenlines 26.700.0`. Имена методов Битрикс24 здесь приведены для сверки с документацией Битрикс24 — обращаться к API нужно по путям Вайбкод из левой колонки.

## Типичные сценарии

| Сценарий | Эндпоинты |
|---|---|
| Исторический отчёт по обращениям за период | [POST /v1/openlines/sessions/search](/docs/openlines/sessions) |
| Real-time монитор очереди и нагрузки операторов | [GET /v1/openlines/operators](/docs/openlines/operators) |
| Дашборд с оценками клиентов (CSAT) | [POST /v1/openlines/ratings/search](/docs/openlines/ratings), [POST /v1/openlines/stats](/docs/openlines/stats) |
| Сводный KPI по линии (по часам и каналам) | [POST /v1/openlines/stats](/docs/openlines/stats) |
| Карточка сессии для разбора жалоб | [POST /v1/openlines/sessions/stats](/docs/openlines/sessions/stats) |
| Анализ переназначений между операторами | [POST /v1/openlines/sessions/transfers](/docs/openlines/sessions/transfers) |

## Рекомендации

- Для сводных показателей используйте `stats` — он считает агрегаты на стороне Битрикс24. Не собирайте те же цифры клиентской агрегацией через `sessions/search`: это упирается в лимит запросов REST Битрикс24.
- `operators` отдаёт почти real-time данные (статус и счётчик активных чатов читаются раздельно). Для виджета мониторинга опрашивайте метод не чаще одного раза в 30 секунд.
- `stats` — тяжёлый метод: запрашивайте его не чаще одного раза в 30–60 секунд и кэшируйте результат на своей стороне.
- Статистика звонков живёт отдельно — `GET /v1/calls/statistics`; статистика Открытых линий использует POST-формы, потому что несёт богатые фильтры.

## Быстрый старт

Агрегаты по линии за июнь:

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/openlines/stats" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dateFrom": "2026-06-01T00:00:00+03:00",
    "dateTo": "2026-06-30T23:59:59+03:00",
    "configId": 3
  }'
```

```json
{
  "success": true,
  "data": {
    "totalSessions": 340,
    "closedSessions": 318,
    "spamSessions": 4,
    "avgWaitAnswer": 42.7,
    "avgSessionDuration": 612.3,
    "likeCount": 210,
    "dislikeCount": 15,
    "votedSessions": 225,
    "positiveRate": 0.9333,
    "kpiFirstAnswerOk": 300,
    "kpiFirstAnswerFail": 18,
    "sessionsBySource": [{ "source": "livechat", "count": 200 }, { "source": "whatsapp", "count": 140 }],
    "sessionsByHour": [0,0,0,0,0,0,2,10,25,40,38,30,28,22,20,25,30,20,15,10,8,5,3,1],
    "sessionsByOperator": [{ "operatorId": 42, "count": 120, "avgWaitAnswer": 38.1, "positiveRate": 0.95 }]
  }
}
```

## Полный пример

Отчёт «обращения за месяц с разбором проблемных сессий»:

1. `POST /v1/openlines/stats` c `dateFrom`/`dateTo` — сводные показатели по линии.
2. `POST /v1/openlines/sessions/search` c тем же периодом и `limit: 50` — первая страница списка сессий. Пагинация по страницам: увеличивайте `offset` на `limit`, пока `data.hasNextPage` равно `true`.
3. `POST /v1/openlines/sessions/stats` c массивом `sessionId` (до 100) — детальные метрики выбранных сессий.

Для стабильной постраничной выгрузки фиксируйте верхнюю границу периода: возьмите `dateCreateTo` равным моменту старта выгрузки. Без фиксированной границы новые сессии, пришедшие во время листания, сдвигают страницы, и записи на стыках могут повториться или пропасть.

## Коды ошибок

### Ошибки Открытых линий

| HTTP | Код | Когда |
|---|---|---|
| 403 | `B24_TARIFF_RESTRICTION` | Тариф портала не включает статистику Открытых линий (право `report_open_lines`) |
| 422 | `METHOD_NOT_YET_AVAILABLE` | Обновление `imopenlines 26.700.0` ещё не приехало на портал. После доезда обновления метод начинает работать; если тариф не включает статистику, код при вызове сменится на `403 B24_TARIFF_RESTRICTION` |
| 400 | `MISSING_PARAMS` | Не переданы обязательные параметры (период у `stats`/`ratings`, `sessionId` у батч-методов) |
| 400 | `INVALID_PARAMS` | Тело запроса не объект, либо нечисловые/некорректные значения там, где ожидаются числа |
| 400 | `BATCH_LIMIT_EXCEEDED` | Массив `sessionId` превышает лимит метода (100 для `sessions/stats`, 50 для `sessions/transfers`) |

При отказе Битрикс24 ответ приходит как `422 BITRIX_ERROR`, а сырой код Битрикс24 дублируется в поле `error.b24Code`:

| `error.b24Code` | Когда |
|---|---|
| `PERIOD_REQUIRED` | Период не распознан Битрикс24 (например, дата в неизвестном формате) |
| `PERIOD_TOO_LARGE` | Период превышает 1 год |
| `INVALID_FILTER` | Недопустимое значение фильтра или формат даты |
| `OFFSET_TOO_LARGE` | `offset` превышает максимум — сузьте период или фильтры |

### Системные ошибки

Общие коды (`SCOPE_DENIED`, `TOKEN_MISSING`, `RATE_LIMITED` и другие) — на странице [Ошибки API](/docs/errors).

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

- [Конфигурация линий](/docs/openlines/config)
- [Чаты и диалоги](/docs/chats)
- [Журнал изменений API](/docs/changelog)