## Channel aggregates for a period

> **The method ships in the `imopenlines 26.700.0` update and is 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` — this means the method has not been released on the account yet, not that the integration is broken.

`POST /v1/openlines/stats`

Summary metrics of Open Channels for a period — session counters, average time to first answer and average session duration, customer satisfaction (CSAT), and breakdowns by connector, hour, and operator. The main method for the summary widgets of a statistics dashboard. The request is resource-intensive: call it no more than once every 30–60 seconds and cache the result.

## Request fields (body)

| Field | Type | Required | Description |
|------|-----|:-----:|---------|
| `dateFrom` | string | yes | Period start, ISO 8601. The `dateFrom`..`dateTo` period must not exceed 1 year |
| `dateTo` | string | yes | Period end, ISO 8601 |
| `configId` | number | no | Open Channel identifier. Source: [`GET /v1/openline-configs`](/docs/openlines/config/list) |
| `configIdList` | number[] | no | List of Open Channel identifiers. Source: [`GET /v1/openline-configs`](/docs/openlines/config/list) |
| `source` | string | no | Connector code, for example `livechat`. Values: the `sessionsBySource[].source` field in the response of this method or `sessions[].source` in the response of [`POST /v1/openlines/sessions/search`](/docs/openlines/sessions/search) |
| `sourceList` | string[] | no | List of connector codes |
| `operatorId` | number | no | Operator identifier. Source: [`GET /v1/users`](/docs/entities/users) |
| `operatorIdList` | number[] | no | List of operator identifiers. Source: [`GET /v1/users`](/docs/entities/users) |

If none of `configId*`/`source*`/`operatorId*` is set, aggregates are computed over all Open Channels available to the current user.

## Examples

### curl — personal key

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

### curl — OAuth application

```bash
curl -X POST "https://vibecode.bitrix24.com/v1/openlines/stats" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dateFrom": "2026-10-01T00:00:00+00:00",
    "dateTo": "2026-10-19T23:59:59+00:00",
    "configId": 59
  }'
```

### JavaScript — personal key

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/openlines/stats', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    dateFrom: '2026-10-01T00:00:00+00:00',
    dateTo: '2026-10-19T23:59:59+00:00',
    configId: 59,
  }),
})
const { data } = await res.json()
```

### JavaScript — OAuth application

```javascript
const res = await fetch('https://vibecode.bitrix24.com/v1/openlines/stats', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    dateFrom: '2026-10-01T00:00:00+00:00',
    dateTo: '2026-10-19T23:59:59+00:00',
    configId: 59,
  }),
})
const { data } = await res.json()
```

## Response fields

When there is no data for the period, numeric metrics are returned as `0`, not `null`. In that case the `sessionsBySource` and `sessionsByOperator` breakdowns arrive as empty arrays.

| Field | Type | Description |
|------|-----|---------|
| `success` | boolean | `true` on a successful request |
| `data` | object | Metrics for the period |
| `data.totalSessions` | number | Number of sessions in the period |
| `data.closedSessions` | number | Number of closed sessions |
| `data.spamSessions` | number | Number of sessions marked as spam |
| `data.avgWaitAnswer` | number | Average time to first answer, seconds |
| `data.avgSessionDuration` | number | Average session duration, seconds |
| `data.likeCount` | number | Number of "like" customer ratings |
| `data.dislikeCount` | number | Number of "dislike" customer ratings |
| `data.votedSessions` | number | Number of sessions with a customer rating |
| `data.positiveRate` | number | Share of positive ratings among rated sessions, from 0 to 1 |
| `data.kpiFirstAnswerOk` | number | Number of sessions where the first answer met the response-time target (SLA) |
| `data.kpiFirstAnswerFail` | number | Number of sessions where the first answer missed the response-time target |
| `data.sessionsBySource` | object[] | Breakdown by connector |
| `data.sessionsBySource[].source` | string | Connector code, for example `livechat` |
| `data.sessionsBySource[].count` | number | Number of sessions from the connector |
| `data.sessionsByHour` | number[] | Exactly 24 numbers — sessions by hour 0–23 in the server time zone of the Bitrix24 account. The element index is the hour |
| `data.sessionsByOperator` | object[] | Breakdown by operator |
| `data.sessionsByOperator[].operatorId` | number | Operator identifier. Employee data: [`GET /v1/users`](/docs/entities/users) |
| `data.sessionsByOperator[].count` | number | Number of the operator's sessions |
| `data.sessionsByOperator[].avgWaitAnswer` | number | Average time to first answer, seconds |
| `data.sessionsByOperator[].positiveRate` | number | Share of positive ratings among the operator's rated sessions, from 0 to 1 |

## Response example

```json
{
  "success": true,
  "data": {
    "totalSessions": 6,
    "closedSessions": 5,
    "spamSessions": 1,
    "avgWaitAnswer": 0,
    "avgSessionDuration": 0,
    "likeCount": 0,
    "dislikeCount": 0,
    "votedSessions": 0,
    "positiveRate": 0,
    "kpiFirstAnswerOk": 0,
    "kpiFirstAnswerFail": 0,
    "sessionsBySource": [
      { "source": "doccheck", "count": 6 }
    ],
    "sessionsByHour": [0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,5,1,0,0,0,0],
    "sessionsByOperator": [
      { "operatorId": 1295, "count": 4, "avgWaitAnswer": 0, "positiveRate": 0 },
      { "operatorId": 1, "count": 2, "avgWaitAnswer": 0, "positiveRate": 0 }
    ]
  }
}
```

## Error response example

`400` — the period is missing:

```json
{
  "success": false,
  "error": { "code": "MISSING_PARAMS", "message": "Required: dateFrom, dateTo (ISO 8601 strings)" }
}
```

## Errors

| HTTP | Code | Description |
|------|-----|----------|
| 400 | `INVALID_JSON_BODY` | The request body did not parse as JSON. JSON is parsed before field validation, so the response says nothing about missing parameters |
| 400 | `INVALID_PARAMS` | The request body is not an object |
| 400 | `MISSING_PARAMS` | `dateFrom` and/or `dateTo` is missing, or the value is not a string or is an empty string |
| 401 | `TOKEN_MISSING` | The key has no configured tokens |
| 403 | `SCOPE_DENIED` | The key has no `imopenlines` scope |
| 403 | `B24_TARIFF_RESTRICTION` | The Bitrix24 plan does not include Open Channels statistics (`report_open_lines`) |
| 422 | `BITRIX_ERROR` (`error.b24Code: INVALID_FILTER`) | An invalid filter value or date format |
| 422 | `BITRIX_ERROR` (`error.b24Code: PERIOD_TOO_LARGE`) | The period exceeds 1 year |
| 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` |

Full list of common API errors — [Errors](/docs/errors).

## See also

- [Operators (real-time)](/docs/openlines/operators)
- [Session search](/docs/openlines/sessions/search)
- [Open Channels](/docs/openlines)