Aggregate Open Channel configurations

POST /v1/openline-configs/aggregate

Counts the number of Open Channel configurations with optional grouping by queue type and other schema fields.

Grouping. groupBy accepts 2 fields: active, queueType — these are the aggregatable fields from GET /v1/openline-configs/fields. The remaining fields (id, name, workTimeFrom, workTimeTo, and other camelCase response fields) are rejected with 400 INVALID_PARAMS when passed in groupBy — details in Known specifics.

Numeric aggregations (sum/avg/min/max) do not apply. Open Channel configuration fields are categorical or identifier fields. Only the count function with field: "*" is supported.

Request fields (body)

Examples

curl — personal key

curl -X POST "https://vibecode.bitrix24.com/v1/openline-configs/aggregate" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "groupBy": "queueType"
  }'

curl — OAuth application

curl -X POST "https://vibecode.bitrix24.com/v1/openline-configs/aggregate" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "groupBy": "queueType"
  }'

JavaScript — personal key

const res = await fetch('https://vibecode.bitrix24.com/v1/openline-configs/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    groupBy: 'queueType',
  }),
})

const { success, data } = await res.json()
console.log('Total configurations:', data.count)
console.log('By queue type:', data.groups)

JavaScript — OAuth application

const res = await fetch('https://vibecode.bitrix24.com/v1/openline-configs/aggregate', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    groupBy: 'queueType',
  }),
})

const { success, data } = await res.json()

To group by multiple fields, pass an array: "groupBy": ["queueType", "active"]. Combinations of the 2 allowed fields are accepted: active, queueType.

Other scenarios

The blocks below are request bodies.

The total number of configurations — the fastest query, without fetching records:

{}

Passing count explicitly via aggregate:

{
  "aggregate": [{ "field": "*", "function": "count" }]
}

Response fields

Response example

Response to the main query (groupBy: "queueType"):

{
  "success": true,
  "data": {
    "count": 10,
    "aggregates": {},
    "groups": [
      { "queueType": "all", "count": 9, "aggregates": {} },
      { "queueType": "evenly", "count": 1, "aggregates": {} }
    ],
    "meta": {
      "totalRecords": 10,
      "recordsProcessed": 10,
      "truncated": false,
      "groupTotal": 2,
      "groupsTruncated": false
    }
  }
}

Without groupBy the data.groups field is absent from the response.

Error response example

400 — the count function with an invalid field name:

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "count aggregate requires field \"*\""
  }
}

Errors

Full list of common API errors — Errors.

Known specifics

The filter parameter is ignored in aggregation. Passing {"filter": {"active": false}} has no effect on the result — the method returns the count across all configurations in your Bitrix24 account. To get counts for a subset, use groupBy (for example, groupBy: ["active"] splits the result by the activity flag) or process the result of POST /v1/openline-configs/search on the client side.

The count function requires field: "*". Passing {"field": "id", "function": "count"} returns 400 INVALID_PARAMS. The only correct format: {"field": "*", "function": "count"}.

groupBy accepts only 2 fields from the Vibecode schema: active, queueType. These are the aggregatable fields from the GET /v1/openline-configs/fields response. The remaining fields (id, name, workTimeFrom, workTimeTo, queueTime, crm, ...) are rejected with 400 INVALID_PARAMS when passed in groupBy, with the message "groupBy field 'X' is not aggregatable on this entity. Available: active, queueType".

The truncation marker travels with the number itself. When a response arrives with meta.truncated: true, the marker truncated: true sits inside every field object in data.aggregates and on every element of data.groups, and data.meta.warnings gains a warning with the code AGGREGATE_TRUNCATED. A client that reads only the number itself therefore sees that it was computed over only some of the records. None of these markers appear on a complete response. Full details — Aggregation POST — the 5000-record ceiling.

See also

• List configurations
• Filtering syntax
• Limits and optimization