# Конфигурации открытых линий

Управление конфигурациями открытых линий Битрикс24: настройка входящих обращений из мессенджеров и социальных сетей, очереди операторов, рабочего времени, интеграции с CRM, приветственных сообщений и оценки качества обслуживания.

Битрикс24 API: `imopenlines.config.*`
Скоуп: `imopenlines`

## Операции

- [Создать конфигурацию](./config/create.md) — `POST /v1/openline-configs`
- [Список конфигураций](./config/list.md) — `GET /v1/openline-configs`
- [Получить конфигурацию](./config/get.md) — `GET /v1/openline-configs/:id`
- [Обновить конфигурацию](./config/update.md) — `PATCH /v1/openline-configs/:id`
- [Удалить конфигурацию](./config/delete.md) — `DELETE /v1/openline-configs/:id`
- [Поиск конфигураций](./config/search.md) — `POST /v1/openline-configs/search`
- [Поля конфигурации](./config/fields.md) — `GET /v1/openline-configs/fields`
- [Агрегация конфигураций](./config/aggregate.md) — `POST /v1/openline-configs/aggregate`

## Действия оператора над диалогом

Помимо CRUD конфигураций есть пара действий, которые выполняет оператор поверх конкретного диалога открытой линии. Оба требуют `imopenlines` скоупа и принимают `chatId` — идентификатор объекта чата (получите его через `imopenlines.session.open` или `imopenlines.dialog.get`; это **не** dialogId с префиксом `chat`):

### `POST /v1/openlines/operator/answer`

Принимает диалог к обработке текущим оператором.

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/openlines/operator/answer" \
  -H "X-Api-Key: $VIBE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chatId": 2043}'
```

Ответ при успехе: `{ "success": true, "data": { "chatId": 2043, "answered": true } }`.

### `POST /v1/openlines/operator/finish`

Завершает диалог от имени текущего оператора.

```bash
curl -X POST "https://vibecode.bitrix24.tech/v1/openlines/operator/finish" \
  -H "X-Api-Key: $VIBE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chatId": 2043}'
```

Ответ при успехе: `{ "success": true, "data": { "chatId": 2043, "finished": true } }`.

### Ошибки операторских эндпоинтов

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `INVALID_CHAT_ID` | `chatId` отсутствует, не является положительным целым или передан в неверном формате |
| 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `imopenlines` |
| 403 | `BITRIX_ACCESS_DENIED` | У оператора недостаточно прав на действие с этим диалогом |
| 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов |
| 502 | `OPENLINE_OPERATOR_FAILED` | Битрикс24 вернул `result: false` — диалог уже взят/завершён другим оператором, либо `chatId` не соответствует активному диалогу открытой линии |
| 422 | `BITRIX_ERROR` | Битрикс24 вернул ошибку: `CHAT_TYPE` (чат не является открытой линией), `USER_ID` (неверный идентификатор пользователя). Детали — в `error.message` |

## Ключевые поля

| Поле | Описание |
|------|---------|
| `id` | Идентификатор конфигурации (число) |
| `name` | Название открытой линии. При создании и обновлении это же поле передаётся в `body` как `LINE_NAME` |
| `active` | Признак активности: `true` — линия принимает обращения, `false` — отключена |
| `queueType` | Алгоритм распределения: `all` — всем операторам, `evenly` — равномерно, `strictly` — строго по очереди |
| `QUEUE` | Массив идентификаторов операторов очереди — приходит только в `GET /v1/openline-configs/:id`. Источник идентификаторов: `GET /v1/users` |
| `WELCOME_BOT_ID` | Идентификатор приветственного бота — бот, с которым начинается диалог до передачи оператору. Источник: `/docs/bots/management/list` |
| `CRM_CREATE` | Признак автоматического создания лида или контакта в CRM при входящем обращении |
| `WORKTIME_ENABLE` | Признак использования расписания рабочего времени |

Полный список полей — [`GET /v1/openline-configs/fields`](./config/fields.md).

## Что нужно знать перед работой

1. **Смешанный регистр полей.** Ответы содержат поля в двух регистрах одновременно: 6 полей в camelCase (`id`, `active`, `name`, `queueType`, `workTimeFrom`, `workTimeTo`) и UPPER_SNAKE_CASE-поля (`CRM_CREATE`, `WORKTIME_ENABLE`, `WELCOME_BOT_ID` и другие). Где какое поле — в [Поля конфигурации](./config/fields.md).
2. **Разный набор полей в `list`/`search` и в `get`.** `GET /v1/openline-configs` и `POST /v1/openline-configs/search` возвращают по 91 полю на запись (6 camelCase + 85 UPPER_SNAKE_CASE). `GET /v1/openline-configs/:id` дополнительно отдаёт 4 поля очереди операторов (`QUEUE`, `QUEUE_FULL`, `QUEUE_USERS_FIELDS`, `QUEUE_ONLINE`) — итого 95 полей.
3. **Минимум для создания — одно поле `LINE_NAME`.** Остальные поля при создании опциональны. Тело запроса передаётся в `UPPER_SNAKE_CASE`.
4. **Адресация по `id`.** Для получения, обновления и удаления используется числовой `id` из ответа. Бывшие «зарезервированные» поля `lineId` и `agentId` удалены из схемы (VB-5ba3fd91) — `imopenlines.config.*` никогда их не возвращал.

## Связанные сущности

| Сущность | Эндпоинт | Назначение |
|----------|----------|-----------|
| Пользователи | `GET /v1/users` | Источник идентификаторов операторов для поля `QUEUE` |
| Боты | `/docs/bots/management/list` | Источник идентификатора приветственного бота для поля `WELCOME_BOT_ID` |

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

1. Получить список конфигураций: [`GET /v1/openline-configs`](./config/list.md).
2. Создать конфигурацию с минимальным набором полей: [`POST /v1/openline-configs`](./config/create.md) с `LINE_NAME`.
3. Получить полную запись с очередью операторов: [`GET /v1/openline-configs/:id`](./config/get.md).
4. Обновить параметры: [`PATCH /v1/openline-configs/:id`](./config/update.md).
5. Удалить конфигурацию: [`DELETE /v1/openline-configs/:id`](./config/delete.md).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Максимум записей на запрос | 200 (`limit ≤ 200`). На типичном портале конфигураций — десятки, одного запроса хватает на всё |
| Пагинация | через `limit` + `offset`. Используйте поле `hasMore` для проверки следующей страницы |
| Batch-доступные операции | `create`, `update`, `delete` — через [`POST /v1/batch`](/docs/batch) |
| Rate limit | общий для Вайбкода — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [Открытые линии](/docs/openlines)
- [Справочник сущностей](/docs/entity-api)
- [Синтаксис фильтрации](/docs/filtering)
- [Batch](/docs/batch)
- [Лимиты и оптимизация](/docs/optimization)