# Open Channel configurations

Manage Bitrix24 Open Channel configurations: set up inbound inquiries from messengers and social networks, operator queues, working hours, CRM integration, welcome messages, and service-quality ratings.

Bitrix24 API: `imopenlines.config.*`
Scope: `imopenlines`

## Operations

- [Create configuration](./config/create.md) — `POST /v1/openline-configs`
- [List configurations](./config/list.md) — `GET /v1/openline-configs`
- [Get configuration](./config/get.md) — `GET /v1/openline-configs/:id`
- [Update configuration](./config/update.md) — `PATCH /v1/openline-configs/:id`
- [Delete configuration](./config/delete.md) — `DELETE /v1/openline-configs/:id`
- [Search configurations](./config/search.md) — `POST /v1/openline-configs/search`
- [Configuration fields](./config/fields.md) — `GET /v1/openline-configs/fields`
- [Aggregate configurations](./config/aggregate.md) — `POST /v1/openline-configs/aggregate`

## Operator actions on a dialog

Besides configuration CRUD, there are four actions an operator performs on a specific Open Channel dialog. Two are described below — accepting a dialog and finishing it. The other two are described in the [Open Channel sessions](./sessions.md) subsection: [intercepting a dialog](./sessions/intercept.md) and [joining a dialog](./sessions/join.md). All four require the `imopenlines` scope.

The `answer` and `finish` described below, like `sessions/intercept` and `sessions/join`, take the Open Channel chat object identifier in `chatId`: the number `2043` or the `chat2043` form. Fractional and too-large numbers are rejected before the call to Bitrix24: `answer` and `finish` respond with `400 INVALID_CHAT_ID`, `sessions/intercept` and `sessions/join` with `400 INVALID_PARAMS`.

Session chat identifiers are returned by [Session search](./sessions/search.md) in the `sessions[].chatId` field. That method ships in the `imopenlines 26.700.0` update and is not yet available on all Bitrix24 accounts. The other source of the same identifier works on every Bitrix24 account — [`GET /v1/openlines/crm/chats`](./crm-chats.md) by a CRM card. A bot receives the same identifier in an event, in the `event.data.chat.id` field.

A bot hands a session over to an operator through [bot session actions](/docs/bots/openlines), not through these methods. They require the `imbot` and `imopenlines` scopes. A bot leaving the chat does not transfer the session.

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

Accepts the dialog for handling by the current operator.

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

Success response: `{ "success": true, "data": { "chatId": 2043, "answered": true } }`.

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

Finishes the dialog on behalf of the current operator.

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

Success response: `{ "success": true, "data": { "chatId": 2043, "finished": true } }`.

### Operator endpoint errors

| HTTP | Code | Description |
|------|-----|---------|
| 400 | `INVALID_CHAT_ID` | `chatId` is missing, is not a positive integer, or is passed in an invalid format |
| 403 | `SCOPE_DENIED` | The API key lacks the `imopenlines` scope |
| 403 | `BITRIX_ACCESS_DENIED` | The operator lacks permission for this dialog action |
| 401 | `TOKEN_MISSING` | The API key has no configured tokens |
| 502 | `OPENLINE_OPERATOR_FAILED` | Bitrix24 returned `result: false` — the dialog has already been taken/finished by another operator, or `chatId` does not match an active Open Channel dialog |
| 422 | `BITRIX_ERROR` | Bitrix24 returned an error: `CHAT_TYPE` (the chat is not an Open Channel), `USER_ID` (invalid user identifier). Details are in `error.message` |

## Key fields

| Field | Description |
|------|---------|
| `id` | Configuration identifier (number) |
| `name` | Open Channel name |
| `active` | Whether the channel is active: `true` — the channel accepts inquiries, `false` — disabled |
| `queueType` | Distribution algorithm: `all` — to all operators, `evenly` — evenly, `strictly` — strictly in order |
| `queue` | Array of queue operator identifiers — returned only in `GET /v1/openline-configs/:id`. Source of identifiers: `GET /v1/users` |
| `welcomeBotId` | Welcome bot user ID — the bot starts the dialog before it is handed to an operator. For an AI agent, use `bitrixBotId` from [`GET /v1/agents`](/docs/agents/list); for a standalone bot, use `id` from `/docs/bots/management/list` |
| `crmCreate` | Type of CRM record automatically created on an inbound inquiry: `none`, `lead`, or `deal` |
| `workTimeEnable` | Whether the working-hours schedule is used |

Full field list — [`GET /v1/openline-configs/fields`](./config/fields.md).

## What to know before you start

1. **Uniform field casing — camelCase.** Top-level fields in the `list`, `get`, and `search` responses arrive in camelCase — `crmCreate`, `workTimeEnable`, `welcomeBotId`, `queueType`. `filter` and `sort` operate on these same names. In [aggregation](./config/aggregate.md), `groupBy` accepts only two fields — `active` and `queueType`. The nested operator-queue objects — `queueFull` and `queueUsersFields` in the `get` response — use UPPER_SNAKE_CASE keys internally (`USER_ID`, `USER_NAME`, `DEPARTMENT_ID`), see [Get configuration](./config/get.md). The full field reference with types and descriptions — [Configuration fields](./config/fields.md).
2. **Different field set in `list`/`search` vs `get`.** `GET /v1/openline-configs` and `POST /v1/openline-configs/search` return 91 fields per record. `GET /v1/openline-configs/:id` additionally returns 4 operator queue fields — `queue`, `queueFull`, `queueUsersFields`, `queueOnline` — 95 fields in total.
3. **The minimum for creation is at least one recognized writable field.** The other fields are optional on create. The request body is passed in camelCase — the canonical case. UPPER_SNAKE_CASE names are also accepted for backward compatibility.
4. **Addressing by `id`.** Get, update, and delete use the numeric `id` from the response. The former "reserved" fields `lineId` and `agentId` were removed from the schema — Bitrix24 never returned them. A Hermes agent is not assigned through `agentId`: pass its bot user in `welcomeBotId`, while human operators use separate user IDs in `queue`.

## Related entities

| Entity | Endpoint | Purpose |
|----------|----------|-----------|
| Users | `GET /v1/users` | Source of operator identifiers for the `queue` field |
| AI agents | `GET /v1/agents` | Source of `bitrixBotId` for the `welcomeBotId` field |
| Bots | `/docs/bots/management/list` | Source of the welcome bot identifier for the `welcomeBotId` field |

## Typical scenario

1. Get the list of configurations: [`GET /v1/openline-configs`](./config/list.md).
2. Create a configuration with a minimal field set: [`POST /v1/openline-configs`](./config/create.md) with `name`.
3. Get the full record with the operator queue: [`GET /v1/openline-configs/:id`](./config/get.md).
4. Update the parameters: [`PATCH /v1/openline-configs/:id`](./config/update.md).
5. Delete the configuration: [`DELETE /v1/openline-configs/:id`](./config/delete.md).

## Limits

| Limit | Value |
|-------|----------|
| Maximum records per request | 200 (`limit ≤ 200`). A typical Bitrix24 account has dozens of configurations — a single request covers them all |
| Pagination | via `limit` + `offset`. Use the `hasMore` field to check for the next page |
| Batch-available operations | `create`, `update`, `delete` — via [`POST /v1/batch`](/docs/batch) |
| Rate limit | shared across the Vibecode API — see [Limits and optimization](/docs/optimization) |

## See also

- [Open Channels](/docs/openlines)
- [API overview](/docs/entity-api)
- [Filtering syntax](/docs/filtering)
- [Batch](/docs/batch)
- [Limits and optimization](/docs/optimization)