# Open Channels

Bitrix24 Open Channels receive client inquiries from messengers and social networks and route them to operators. The methods in this section configure channels, run dialogs on behalf of an operator, link dialogs to CRM cards, and read contact-center statistics.

**Scope:** `imopenlines` | **Base URL:** `https://vibecode.bitrix24.com/v1` | **Authorization:** `X-Api-Key`

[Quick start](#quick-start) | [Full example](#full-example) | [Endpoint reference](#endpoint-reference) | [Error codes](#error-codes)

## Documentation sections

- [Open Channel configurations](/docs/openlines/config) — create, read, update, delete and search channels, plus accepting and finishing a dialog as an operator
- [Open Channel quick replies](/docs/openlines/quick-replies) — channel reply templates: list, create, update, delete
- [Open Channel sessions](/docs/openlines/sessions) — session search, session metrics, reassignments and correspondence, opening a client chat, starting a session, intercepting a dialog, joining a dialog and sending a CRM form to a customer
- [Chats by CRM card](/docs/openlines/crm-chats) — channel dialogs linked to a lead, deal, company or contact
- [CRM chat actions](/docs/openlines/crm) — add an employee to a CRM chat and remove them, message the client, create a lead from an inquiry
- [Dialog metadata](/docs/openlines/dialog) — the dialog card and channel ID by `chatId`, `dialogId` or `sessionId`
- [Session history](/docs/openlines/history) — the correspondence of the chat's latest session in a single response
- [Operator actions and my pause](/docs/openlines/operator) — skip, transfer, mark the client as spam, finish another operator's dialog, manage your own operator pause
- [Channel aggregates for a period](/docs/openlines/stats) — channel summary metrics for a monitoring dashboard
- [Operators (real-time)](/docs/openlines/operators) — operator status and load
- [Ratings (CSAT)](/docs/openlines/ratings) — sessions with a client rating for a period

## Identifiers

| Identifier | What it is | Where to get it |
|---|---|---|
| `configId`, `lineId` | Open Channel | The `data[].id` field in the [`GET /v1/openline-configs`](/docs/openlines/config/list) response |
| `sessionId` | A single client inquiry | The `sessions[].id` field in the [`POST /v1/openlines/sessions/search`](/docs/openlines/sessions/search) response |
| `chatId` | Open Channel chat, shared by all sessions of a client | The `sessions[].chatId` field in the [`POST /v1/openlines/sessions/search`](/docs/openlines/sessions/search) response, the `data[].chatId` field in the [`GET /v1/openlines/crm/chats`](/docs/openlines/crm-chats) response for a CRM card, or [`POST /v1/openlines/sessions/open`](/docs/openlines/sessions/open) by client code |

Dialog actions run on behalf of the employee the key is bound to. They have no "employee" parameter — details in [Operator actions and my pause](/docs/openlines/operator).

## Statistics (dashboard)

> **The statistics methods ship in the `imopenlines 26.700.0` update and are not yet available on all Bitrix24 accounts.** If the update has not reached your Bitrix24 account yet, the API returns `422 METHOD_NOT_YET_AVAILABLE` — a sign that the method is not yet released on the account, not an integration error.

Six methods only read data: channel summary metrics, real-time operators, sessions with filters, metrics of selected sessions, client ratings and reassignment history. Data is limited to the permissions of the employee the key is bound to. If that employee has no access to any channel, the method returns an empty list or zero metrics rather than an error. The methods require the Open Channels statistics permission `report_open_lines`; without it, the request returns `403 B24_TARIFF_RESTRICTION`.

| Endpoint | Purpose |
|---|---|
| [`POST /v1/openlines/stats`](/docs/openlines/stats) | Channel aggregates for a period |
| [`GET /v1/openlines/operators`](/docs/openlines/operators) | Operator status and load |
| [`POST /v1/openlines/sessions/search`](/docs/openlines/sessions/search) | Session search with filters |
| [`POST /v1/openlines/sessions/stats`](/docs/openlines/sessions/stats) | Metrics of selected sessions, up to 100 per call |
| [`POST /v1/openlines/ratings/search`](/docs/openlines/ratings) | Sessions with a client rating for a period |
| [`POST /v1/openlines/sessions/transfers`](/docs/openlines/sessions/transfers) | Reassignment history, up to 50 sessions per call |

The other methods in the section work on any Bitrix24 account. The exception is [Session history](/docs/openlines/history): the Vibecode platform enables it gradually, and until it is enabled the call returns `403 OPENLINES_HISTORY_DISABLED`. Session history requires neither the `report_open_lines` permission nor the `imopenlines 26.700.0` update.

## Common scenarios

| Scenario | Endpoints |
|---|---|
| Report on inquiries for a period | [`POST /v1/openlines/stats`](/docs/openlines/stats), [`POST /v1/openlines/sessions/search`](/docs/openlines/sessions/search) |
| Queue and operator load monitor | [`GET /v1/openlines/operators`](/docs/openlines/operators) |
| Client rating dashboard (CSAT) | [`POST /v1/openlines/ratings/search`](/docs/openlines/ratings), [`POST /v1/openlines/stats`](/docs/openlines/stats) |
| Investigating a complaint about one session | [`POST /v1/openlines/sessions/stats`](/docs/openlines/sessions/stats), [`POST /v1/openlines/sessions/history`](/docs/openlines/history) |
| Analyzing reassignments between operators | [`POST /v1/openlines/sessions/transfers`](/docs/openlines/sessions/transfers) |
| Connect to a client dialog from a CRM card | [`GET /v1/openlines/crm/chats`](/docs/openlines/crm-chats), [`POST /v1/openlines/sessions/intercept`](/docs/openlines/sessions/intercept) or [`POST /v1/openlines/sessions/join`](/docs/openlines/sessions/join) |
| Message the client in a CRM card dialog | [`GET /v1/openlines/crm/chats`](/docs/openlines/crm-chats), [`POST /v1/openlines/crm/messages`](/docs/openlines/crm/messages) |
| Take a dialog and transfer it to a colleague | [`POST /v1/openlines/sessions/start`](/docs/openlines/sessions/start), [`POST /v1/openlines/operator/transfer`](/docs/openlines/operator/transfer) |

## Recommendations

- Get summary metrics from [`POST /v1/openlines/stats`](/docs/openlines/stats) — it computes them on the Bitrix24 side. Collecting the same figures by paging through [`POST /v1/openlines/sessions/search`](/docs/openlines/sessions/search) consumes the request limit.
- The polling frequency for summary metrics and real-time operators is given on the [Channel aggregates for a period](/docs/openlines/stats) and [Operators (real-time)](/docs/openlines/operators) pages.

## Quick start

Get a channel ID and that channel's summary metrics for a period.

### 1. Find the channel

```bash
curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://vibecode.bitrix24.com/v1/openline-configs"
```

In the response, `data` is the array of channels on the Bitrix24 account. The `data[].id` field is the channel ID, `data[].name` is its name.

### 2. Request the channel's summary metrics

```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-09-01T00:00:00+00:00",
    "dateTo": "2026-09-30T23:59:59+00:00",
    "configId": 3
  }'
```

Response:

```json
{
  "success": true,
  "data": {
    "totalSessions": 3,
    "closedSessions": 2,
    "spamSessions": 0,
    "avgWaitAnswer": 25,
    "avgSessionDuration": 17.3333,
    "likeCount": 0,
    "dislikeCount": 0,
    "votedSessions": 0,
    "positiveRate": 0,
    "kpiFirstAnswerOk": 0,
    "kpiFirstAnswerFail": 0,
    "sessionsBySource": [{ "source": "livechat", "count": 2 }, { "source": "telegrambot", "count": 1 }],
    "sessionsByHour": [1,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,1,0,0,0,0],
    "sessionsByOperator": [{ "operatorId": 42, "count": 2, "avgWaitAnswer": 25, "positiveRate": 0 }]
  }
}
```

Response fields are on the [Channel aggregates for a period](/docs/openlines/stats) page.

## Full example

A report on a channel's inquiries for a period: summary metrics, sessions linked to CRM, their metrics, and all dialogs of the first session's CRM card. All calls only read data.

```javascript
const VIBE_KEY = process.env.VIBE_KEY
const BASE = 'https://vibecode.bitrix24.com/v1'

async function api(method, path, body = null) {
  const opts = { method, headers: { 'X-Api-Key': VIBE_KEY } }
  if (body) {
    opts.headers['Content-Type'] = 'application/json'
    opts.body = JSON.stringify(body)
  }
  const res = await fetch(`${BASE}${path}`, opts)
  return res.json()
}

// 1. Channels on the account: take the ID of the first channel
const lines = await api('GET', '/openline-configs')
const configId = lines.data[0].id
console.log('Channel:', configId)

// 2. Channel summary metrics for the period
const period = { dateFrom: '2026-10-01T00:00:00+00:00', dateTo: '2026-10-19T23:59:59+00:00' }
const stats = await api('POST', '/openlines/stats', { ...period, configId })
console.log('Inquiries:', stats.data.totalSessions, 'closed:', stats.data.closedSessions)

// 3. Sessions of the same period linked to CRM
const found = await api('POST', '/openlines/sessions/search', {
  configId,
  dateCreateFrom: period.dateFrom,
  dateCreateTo: period.dateTo,
  hasCrm: 'Y',
  limit: 50,
})
const sessions = found.data.sessions
console.log('Sessions on page:', sessions.length, 'more:', found.data.hasNextPage)

if (sessions.length > 0) {
  // 4. Metrics of the sessions found, up to 100 per call
  const metrics = await api('POST', '/openlines/sessions/stats', {
    sessionId: sessions.map((s) => s.id),
  })
  for (const m of metrics.data.sessions) console.log('Session', m.sessionId, 'messages:', m.messagesCount)

  // 5. All dialogs of the CRM card the first session is linked to
  const { crmEntityType, crmEntityId } = sessions[0]
  const chats = await api('GET', `/openlines/crm/chats?crmEntityType=${crmEntityType}&crmEntityId=${crmEntityId}&activeOnly=false`)
  for (const c of chats.data) console.log('Chat', c.chatId, 'channel:', c.connectorTitle)
}
```

How to get the next pages of sessions is described in the "Pagination" paragraph on the [Session search](/docs/openlines/sessions/search) page. The `chatId` found in step 5 is accepted by [dialog interception](/docs/openlines/sessions/intercept), [joining a dialog](/docs/openlines/sessions/join) and [a message to the client](/docs/openlines/crm/messages).

## Endpoint reference

All 39 endpoints in the section:

| Method | Path | Bitrix24 method | Description |
|-------|------|---------------|---------|
| POST | [/v1/openline-configs](/docs/openlines/config/create) | imopenlines.config.add | Create a channel configuration |
| GET | [/v1/openline-configs](/docs/openlines/config/list) | imopenlines.config.list.get | List configurations |
| GET | [/v1/openline-configs/:id](/docs/openlines/config/get) | imopenlines.config.get | Configuration by ID, with the operator queue |
| PATCH | [/v1/openline-configs/:id](/docs/openlines/config/update) | imopenlines.config.update | Update a configuration |
| DELETE | [/v1/openline-configs/:id](/docs/openlines/config/delete) | imopenlines.config.delete | Delete a configuration |
| POST | [/v1/openline-configs/search](/docs/openlines/config/search) | imopenlines.config.list.get | Search configurations by filter |
| GET | [/v1/openline-configs/fields](/docs/openlines/config/fields) | — | Configuration field schema |
| POST | [/v1/openline-configs/aggregate](/docs/openlines/config/aggregate) | imopenlines.config.list.get | Aggregation over configurations |
| POST | [/v1/openlines/operator/answer](/docs/openlines/config) | imopenlines.operator.answer | Accept a dialog as an operator |
| POST | [/v1/openlines/operator/finish](/docs/openlines/config) | imopenlines.operator.finish | Finish a dialog as an operator |
| GET | [/v1/openline-configs/:lineId/quick-replies](/docs/openlines/quick-replies/list) | imopenlines.v2.QuickReply.list | List the channel's quick replies and sections |
| POST | [/v1/openline-configs/:lineId/quick-replies](/docs/openlines/quick-replies/create) | imopenlines.v2.QuickReply.save | Create a quick reply |
| PATCH | [/v1/openline-configs/:lineId/quick-replies/:id](/docs/openlines/quick-replies/update) | imopenlines.v2.QuickReply.save | Update a quick reply |
| DELETE | [/v1/openline-configs/:lineId/quick-replies/:id](/docs/openlines/quick-replies/delete) | imopenlines.v2.QuickReply.delete | Delete a quick reply |
| POST | [/v1/openlines/sessions/search](/docs/openlines/sessions/search) | imopenlines.v2.Session.list | Session search with filters |
| POST | [/v1/openlines/sessions/stats](/docs/openlines/sessions/stats) | imopenlines.v2.Session.Stat.get | Metrics of selected sessions, up to 100 per call |
| POST | [/v1/openlines/sessions/transfers](/docs/openlines/sessions/transfers) | imopenlines.v2.Session.Transfer.list | Reassignment history, up to 50 sessions per call |
| POST | [/v1/openlines/sessions/history](/docs/openlines/history) | imopenlines.session.history.get | Correspondence of the chat's latest session by `chatId` |
| POST | [/v1/openlines/sessions/open](/docs/openlines/sessions/open) | imopenlines.session.open | Open a client chat by its code in the connector |
| POST | [/v1/openlines/sessions/start](/docs/openlines/sessions/start) | imopenlines.session.start | Start a session: the employee becomes the chat operator |
| POST | [/v1/openlines/sessions/intercept](/docs/openlines/sessions/intercept) | imopenlines.session.intercept | Intercept a dialog for the current operator |
| POST | [/v1/openlines/sessions/join](/docs/openlines/sessions/join) | imopenlines.session.join | Join a dialog as an additional participant |
| POST | [/v1/openlines/sessions/send-form](/docs/openlines/send-form) | imopenlines.dialog.form.send | Send a CRM form to a customer in a dialog |
| GET | [/v1/openlines/crm/chats](/docs/openlines/crm-chats) | imopenlines.crm.chat.get | Channel chats linked to a CRM card |
| POST | [/v1/openlines/crm/chats/users](/docs/openlines/crm/members-create) | imopenlines.crm.chat.user.add | Add an employee to a CRM chat |
| DELETE | [/v1/openlines/crm/chats/users](/docs/openlines/crm/members-delete) | imopenlines.crm.chat.user.delete | Remove an employee from a CRM chat |
| POST | [/v1/openlines/crm/messages](/docs/openlines/crm/messages) | imopenlines.crm.message.add | Send a message to the client |
| POST | [/v1/openlines/dialogs/:chatId/lead](/docs/openlines/crm/lead) | imopenlines.crm.lead.create | Create a lead from an inquiry |
| POST | [/v1/openlines/dialogs/lookup](/docs/openlines/dialog) | imopenlines.dialog.get | Dialog metadata and channel ID by `chatId`, `dialogId` or `sessionId` |
| POST | [/v1/openlines/operator/skip](/docs/openlines/operator/skip) | imopenlines.operator.skip | Skip a dialog |
| POST | [/v1/openlines/operator/spam](/docs/openlines/operator/spam) | imopenlines.operator.spam | Mark the client as spam and close the dialog |
| POST | [/v1/openlines/operator/transfer](/docs/openlines/operator/transfer) | imopenlines.operator.transfer | Transfer a dialog to an employee or to the channel queue |
| POST | [/v1/openlines/operator/finish-another](/docs/openlines/operator/finish-another) | imopenlines.operator.another.finish | Finish another operator's dialog |
| GET | [/v1/openlines/operator/pause](/docs/openlines/operator/pause) | imopenlines.operator.pause.get | Read your own operator pause |
| POST | [/v1/openlines/operator/pause](/docs/openlines/operator/pause-start) | imopenlines.operator.pause.start | Start your own operator pause |
| DELETE | [/v1/openlines/operator/pause](/docs/openlines/operator/pause-stop) | imopenlines.operator.pause.stop | Stop your own operator pause |
| POST | [/v1/openlines/stats](/docs/openlines/stats) | imopenlines.v2.Stat.get | Channel aggregates for a period |
| GET | [/v1/openlines/operators](/docs/openlines/operators) | imopenlines.v2.Operator.list | Operator status and load |
| POST | [/v1/openlines/ratings/search](/docs/openlines/ratings) | imopenlines.v2.Session.Rating.list | Sessions with a client rating for a period |

Accepting and finishing a dialog as an operator are described on the [Open Channel configurations](/docs/openlines/config) page. The six statistics methods ship in the `imopenlines 26.700.0` update, see [Statistics (dashboard)](#statistics-dashboard). `GET /v1/openline-configs/fields` makes no Bitrix24 call — Vibecode returns the field schema itself.

## Error codes

### Open Channels errors

| HTTP | Code | When |
|---|---|---|
| 400 | `INVALID_JSON_BODY` | The request body did not parse as JSON. The check runs before field validation, so the response says nothing about missing parameters. This is the response of the statistics, session history, dialog metadata, CRM chat, interception and joining, and quick reply methods. Creating, updating and searching channel configurations, operator actions, the operator pause, and opening and starting a session respond to such a body with `400 FST_ERR_CTP_INVALID_JSON_BODY` |
| 400 | `MISSING_PARAMS` | Required parameters are missing, for example the period for `stats` and `ratings/search`, `sessionId` for `sessions/stats` and `sessions/transfers` |
| 400 | `INVALID_PARAMS` | The request body is not an object, or a value is invalid where a number or a value from a list is expected |
| 400 | `BATCH_LIMIT_EXCEEDED` | The `sessionId` array exceeds the method limit: 100 for `sessions/stats`, 50 for `sessions/transfers` |
| 403 | `B24_TARIFF_RESTRICTION` | The portal's plan does not include Open Channels statistics — the `report_open_lines` permission |
| 403 | `OPENLINES_HISTORY_DISABLED` | [Session history](/docs/openlines/history) is not yet enabled on the Vibecode platform |
| 422 | `METHOD_NOT_YET_AVAILABLE` | The `imopenlines 26.700.0` update has not reached the portal yet. The response contains an `error.release` field set to `imopenlines 26.700.0` — [code details](/docs/errors/platform#method_not_yet_available-422). If the plan does not include statistics, the code changes to `403 B24_TARIFF_RESTRICTION` once the update arrives |
| 502 | `OPENLINE_OPERATOR_FAILED` | Bitrix24 did not confirm the action or returned a response of an unexpected shape. This is the response of accepting and finishing a dialog as an operator, operator actions and the operator pause, opening and starting a session, CRM chat operations and quick replies. The condition for a specific method is in the `## Errors` table on its page |

When Bitrix24 rejects a request, the response comes as `422 BITRIX_ERROR`, and the Bitrix24 code is duplicated in the `error.b24Code` field:

| `error.b24Code` | When |
|---|---|
| `PERIOD_TOO_LARGE` | The period exceeds 1 year |
| `INVALID_FILTER` | Invalid filter value or date format |
| `OFFSET_TOO_LARGE` | `offset` exceeds the maximum — narrow the period or the filters |

The codes of a specific method are in the `## Errors` table on its page.

### System errors

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

## See also

- [Open Channel bot](/docs/bots/openlines)
- [Chats and messages](/docs/chats)
- [API changelog](/docs/changelog)