# Open Channels

Bitrix24 Open Channels (the `imopenlines` module) — inbound inquiries from messengers and social networks, routing to operators, CRM integration, and service-quality ratings. The section covers two facets of the module: managing channel settings and the contact-center manager's dashboard statistics.

- **Base URL:** `https://vibecode.bitrix24.com`
- **Authentication:** the `X-Api-Key` header (personal key) or `X-Api-Key` + `Authorization: Bearer` (OAuth application)
- **Key scope:** `imopenlines`

## What the section covers

| Facet | Purpose | Documentation |
|---|---|---|
| Channel configuration | CRUD for channel settings: operator queue, working hours, CRM integration, welcome message, ratings | [Channel configuration](/docs/openlines/config) |
| Statistics (dashboard) | Read-only: aggregates, sessions, operators, CSAT, transfers | below in this section |

## Identifiers

| Identifier | What it is | Where to get it |
|---|---|---|
| `configId` | Open Channel | [`GET /v1/openline-configs`](/docs/openlines/config/list) |
| `sessionId` | Open Channel session (dialog) | [`POST /v1/openlines/sessions/search`](/docs/openlines/sessions) |
| `chatId` | IM chat bound to the session | the `chatId` field in the `sessions/search` response |

## Channel configuration

Managing Open Channel settings — create, list, get, update, delete, search. Generally available, no rollout required. Two operator actions on a dialog live here as well — answer (`answer`) and finish (`finish`).

Full documentation: [Channel configuration](/docs/openlines/config).

## Statistics (dashboard)

> ⚠️ **The statistics methods are being rolled out — they ship in the `imopenlines 26.700.0` update.** They are not available on all Bitrix24 portals yet. If the methods are not yet available on your portal, the API returns `422 METHOD_NOT_YET_AVAILABLE` — this is not an integration error but a sign that the update has not reached the portal yet.

A list of inquiries with metrics, real-time operator load, per-channel aggregates, customer ratings (CSAT), and transfer history. All methods are read-only. Data is visible within the permissions of the user the key acts on behalf of: if that user has no access to any channel, the method returns an empty result (or zero aggregates) rather than an error. The methods need access to Open Channels statistics (the `report_open_lines` permission); without it, a request returns `403 B24_TARIFF_RESTRICTION`.

| Endpoint | Bitrix24 method | Purpose |
|---|---|---|
| [`POST /v1/openlines/stats`](/docs/openlines/stats) | `imopenlines.v2.Stat.get` | Per-channel aggregates for a period |
| [`GET /v1/openlines/operators`](/docs/openlines/operators) | `imopenlines.v2.Operator.list` | Operators: status and load (real-time) |
| [`POST /v1/openlines/sessions/search`](/docs/openlines/sessions) | `imopenlines.v2.Session.list` | Session list with filters |
| [`POST /v1/openlines/sessions/stats`](/docs/openlines/sessions/stats) | `imopenlines.v2.Session.Stat.get` | Metrics for specific sessions (up to 100) |
| [`POST /v1/openlines/ratings/search`](/docs/openlines/ratings) | `imopenlines.v2.Session.Rating.list` | Rated sessions (CSAT) for a period |
| [`POST /v1/openlines/sessions/transfers`](/docs/openlines/sessions/transfers) | `imopenlines.v2.Session.Transfer.list` | Transfer history (up to 50 sessions) |

All six methods ship in the `imopenlines 26.700.0` update. The Bitrix24 method names are listed here for cross-referencing with the Bitrix24 documentation — call the API using the Vibecode paths in the left column.

## Common scenarios

| Scenario | Endpoints |
|---|---|
| Historical report on inquiries for a period | [POST /v1/openlines/sessions/search](/docs/openlines/sessions) |
| Real-time monitor of the queue and operator load | [GET /v1/openlines/operators](/docs/openlines/operators) |
| Dashboard with customer ratings (CSAT) | [POST /v1/openlines/ratings/search](/docs/openlines/ratings), [POST /v1/openlines/stats](/docs/openlines/stats) |
| Summary KPI per channel (by hour and source) | [POST /v1/openlines/stats](/docs/openlines/stats) |
| Session card for complaint review | [POST /v1/openlines/sessions/stats](/docs/openlines/sessions/stats) |
| Analysis of transfers between operators | [POST /v1/openlines/sessions/transfers](/docs/openlines/sessions/transfers) |

## Recommendations

- For summary metrics use `stats` — it computes aggregates on the Bitrix24 side. Do not assemble the same figures with client-side aggregation over `sessions/search`: that runs into the Bitrix24 REST request limit.
- `operators` returns near-real-time data (status and the active-chat counter are read separately). For a monitoring widget, poll the method no more than once every 30 seconds.
- `stats` is a heavy method: request it no more than once every 30–60 seconds and cache the result on your side.
- Call statistics live separately — `GET /v1/calls/statistics`; Open Channels statistics use POST forms because they carry rich filters.

## Quick start

Per-channel aggregates for June:

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/openlines/stats" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dateFrom": "2026-06-01T00:00:00+00:00",
    "dateTo": "2026-06-30T23:59:59+00: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 }]
  }
}
```

## Full example

Report "inquiries for the month with a review of problem sessions":

1. `POST /v1/openlines/stats` with `dateFrom`/`dateTo` — summary metrics for the channel.
2. `POST /v1/openlines/sessions/search` with the same period and `limit: 50` — the first page of the session list. Page-by-page pagination: increase `offset` by `limit` while `data.hasNextPage` equals `true`.
3. `POST /v1/openlines/sessions/stats` with an array of `sessionId` (up to 100) — detailed metrics for the selected sessions.

For a stable page-by-page export, fix the upper bound of the period: set `dateCreateTo` to the moment the export starts. Without a fixed bound, new sessions arriving during paging shift the pages, and records at the boundaries may be duplicated or lost.

## Error codes

### Open Channels errors

| HTTP | Code | When |
|---|---|---|
| 403 | `B24_TARIFF_RESTRICTION` | The portal tariff does not include Open Channels statistics (the `report_open_lines` permission) |
| 422 | `METHOD_NOT_YET_AVAILABLE` | The `imopenlines 26.700.0` update has not reached the portal yet. Once the update arrives the method starts working; if the tariff does not include statistics, the code returned on the call changes to `403 B24_TARIFF_RESTRICTION` |
| 400 | `MISSING_PARAMS` | Required parameters are missing (the period for `stats`/`ratings`, `sessionId` for the batch methods) |
| 400 | `INVALID_PARAMS` | The request body is not an object, or non-numeric/invalid values where numbers are expected |
| 400 | `BATCH_LIMIT_EXCEEDED` | The `sessionId` array exceeds the method limit (100 for `sessions/stats`, 50 for `sessions/transfers`) |

When Bitrix24 rejects the call, the response arrives as `422 BITRIX_ERROR`, and the raw Bitrix24 code is duplicated in the `error.b24Code` field:

| `error.b24Code` | When |
|---|---|
| `PERIOD_REQUIRED` | Bitrix24 did not recognize the period (for example, a date in an unknown format) |
| `PERIOD_TOO_LARGE` | The period exceeds 1 year |
| `INVALID_FILTER` | An invalid filter value or date format |
| `OFFSET_TOO_LARGE` | `offset` exceeds the maximum — narrow the period or filters |

### System errors

Common codes (`SCOPE_DENIED`, `TOKEN_MISSING`, `RATE_LIMITED`, and others) are on the [API errors](/docs/errors) page.

## See also

- [Channel configuration](/docs/openlines/config)
- [Chats and dialogs](/docs/chats)
- [API changelog](/docs/changelog)