# Open Channel configurations

Manage Bitrix24 Open Channel configurations: handling inbound messages 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 a couple of actions an operator performs on top of a specific Open Channel dialog. Both require the `imopenlines` scope and accept `chatId` — the chat object identifier (get it via `imopenlines.session.open` or `imopenlines.dialog.get`; this is **not** the dialogId with the `chat` prefix):

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

Takes the dialog for handling by the current operator.

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/openlines/operator/answer" \
  -H "X-Api-Key: $VIBE_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: $VIBE_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. On write, the canonical name is camelCase `name`; the B24-native `LINE_NAME` is also accepted |
| `active` | Activity flag: `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` |
| `WELCOME_BOT_ID` | Welcome bot identifier — the bot the dialog starts with before being handed to an operator. Source: `/docs/bots/management/list` |
| `CRM_CREATE` | Flag for automatically creating a lead or contact in CRM on an inbound inquiry |
| `WORKTIME_ENABLE` | Flag for using the working-hours schedule |

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

## What you need to know before you start

1. **Mixed field case.** Responses contain fields in two cases at once: 6 fields in camelCase (`id`, `active`, `name`, `queueType`, `workTimeFrom`, `workTimeTo`) and UPPER_SNAKE_CASE fields (`CRM_CREATE`, `WORKTIME_ENABLE`, `WELCOME_BOT_ID`, and others). Which field is which — see [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 (6 camelCase + 85 UPPER_SNAKE_CASE). `GET /v1/openline-configs/:id` additionally returns 4 operator queue fields (`QUEUE`, `QUEUE_FULL`, `QUEUE_USERS_FIELDS`, `QUEUE_ONLINE`) — 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); B24-native UPPER_SNAKE_CASE is 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 (VB-5ba3fd91) — `imopenlines.config.*` never returned them.

## Related entities

| Entity | Endpoint | Purpose |
|----------|----------|-----------|
| Users | `GET /v1/users` | Source of operator identifiers for the `QUEUE` field |
| Bots | `/docs/bots/management/list` | Source of the welcome bot identifier for the `WELCOME_BOT_ID` 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 tens of configurations — one request is enough for everything |
| 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 Vibecode — see [Limits and optimization](/docs/optimization) |

## See also

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