لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/openlines/sessions.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Open Channel sessions

A session is one client inquiry in an Open Channel chat, from the first message until it is closed. One chat goes through several sessions. The methods in this section search sessions, read their metrics, reassignment history and message history, open a client chat and connect an operator to a dialog.

Bitrix24 API: imopenlines.v2.Session.*, imopenlines.session.* Scope: imopenlines

Method availability

Session search, per-session metrics and reassignment history ship in the imopenlines 26.700.0 update. Until the update reaches the Bitrix24 account, they return 422 METHOD_NOT_YET_AVAILABLE. The other methods of this section work on any Bitrix24 account. Session history is being enabled gradually by the Vibecode platform and returns 403 OPENLINES_HISTORY_DISABLED until it is enabled.

Identifiers

The methods of this section take two different identifiers:

Identifier What it is Where to get it
IdentifiersessionId What it isOne client inquiry Where to get itThe sessions[].id field in the POST /v1/openlines/sessions/search response
IdentifierchatId What it isOpen Channel chat shared by all sessions of a client Where to get itThe sessions[].chatId field in the POST /v1/openlines/sessions/search response, GET /v1/openlines/crm/chats by CRM card, or POST /v1/openlines/sessions/open by client code

Starting a session, intercepting a dialog and joining it work only on behalf of the employee the key is bound to — the same rule as for operator actions.

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/sessions/search

A list of Open Channel sessions with filters and pagination — the main method for detailed reports and export to external analytics systems. An empty body {} returns the first page of all visible sessions.

Request fields (body)

Field Type Required Description
FieldconfigId Typenumber Requiredno DescriptionOpen Channel identifier. Source: GET /v1/openline-configs
FieldconfigIdList Typenumber[] Requiredno DescriptionList of Open Channel identifiers. Source: GET /v1/openline-configs
FieldoperatorId Typenumber Requiredno DescriptionOperator identifier. Source: GET /v1/users
FieldoperatorIdList Typenumber[] Requiredno DescriptionList of operator identifiers. Source: GET /v1/users
Fieldsource Typestring Requiredno DescriptionConnector code, for example livechat. Values: the sessions[].source field in this method's response or sessionsBySource[].source in the POST /v1/openlines/stats response
FieldsourceList Typestring[] Requiredno DescriptionList of connector codes
Fieldstatus Typestring Requiredno DescriptionSession status: new / answered / closed / spam / paused
FieldcloseReason Typestring Requiredno DescriptionClose reason: operator / auto / spam / client / replyLimit
FielddateCreateFrom Typestring Requiredno DescriptionStart of the creation period, ISO 8601. The dateCreateFrom..dateCreateTo period must not exceed 1 year
FielddateCreateTo Typestring Requiredno DescriptionEnd of the creation period, ISO 8601
FielddateCloseFrom Typestring Requiredno DescriptionStart of the closing period, ISO 8601
FielddateCloseTo Typestring Requiredno DescriptionEnd of the closing period, ISO 8601
Fieldvote Typestring Requiredno DescriptionClient rating: like / dislike / none / any
FieldhasVoteHead Typestring Requiredno DescriptionWhether there is a supervisor rating: Y / N
FieldkpiFirstAnswer Typestring Requiredno DescriptionWhether the first-answer time target (SLA) was met: Y / N. Requires a bounded period (dateCreateFrom+dateCreateTo or dateCloseFrom+dateCloseTo)
FieldhasCrm Typestring Requiredno DescriptionWhether there is a CRM binding: Y / N
FieldwaitAnswerFrom Typenumber Requiredno DescriptionMin. time to first answer, seconds
FieldwaitAnswerTo Typenumber Requiredno DescriptionMax. time to first answer, seconds
FieldwaitCloseFrom Typenumber Requiredno DescriptionMin. time to close, seconds
FieldwaitCloseTo Typenumber Requiredno DescriptionMax. time to close, seconds
Fieldorder Typestring Requiredno DescriptionSort field: dateCreate / dateClose / waitAnswer / waitClose (default dateCreate)
FieldorderDirection Typestring Requiredno DescriptionDirection: asc / desc (default desc)
Fieldlimit Typenumber Requiredno DescriptionPage size, 1..200 (default 50). An out-of-range value does not cause an error — a page of 50 records is returned
Fieldoffset Typenumber Requiredno DescriptionPagination offset (default 0)

The status and closeReason filters are mutually exclusive: closeReason already implies a closed session. The hasVoteHead filter applies only to Open Channels where the user has the supervisor rating permission.

There is no filter by CRM entity type — for CRM only the hasCrm flag is available (whether a binding exists). To select a specific type, filter on your side by the crmEntityType / crmEntityId fields from the response.

Pagination. The next page is the same request with offset increased by limit, while data.hasNextPage is true. When exporting page by page, pin the upper bound of the period — set dateCreateTo to the moment the export starts. Without a fixed bound, new sessions arriving during the export shift the pages, and records at page boundaries may repeat or go missing.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/openlines/sessions/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "configId": 1,
    "status": "closed",
    "dateCreateFrom": "2024-05-01T00:00:00+00:00",
    "dateCreateTo": "2024-05-31T23:59:59+00:00",
    "limit": 2
  }'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/openlines/sessions/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "configId": 1,
    "status": "closed",
    "dateCreateFrom": "2024-05-01T00:00:00+00:00",
    "dateCreateTo": "2024-05-31T23:59:59+00:00",
    "limit": 2
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/openlines/sessions/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    configId: 1,
    status: 'closed',
    dateCreateFrom: '2024-05-01T00:00:00+00:00',
    dateCreateTo: '2024-05-31T23:59:59+00:00',
    limit: 2,
  }),
})
const { data } = await res.json()

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/openlines/sessions/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    configId: 1,
    status: 'closed',
    dateCreateFrom: '2024-05-01T00:00:00+00:00',
    dateCreateTo: '2024-05-31T23:59:59+00:00',
    limit: 2,
  }),
})
const { data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on a successful response
Fielddata.sessions Typearray DescriptionSessions of the current page. An empty array if nothing matches the filters
Fielddata.sessions[].id Typenumber DescriptionSession identifier
Fielddata.sessions[].configId Typenumber DescriptionOpen Channel identifier. Open Channel details: GET /v1/openline-configs/:id
Fielddata.sessions[].source Typestring DescriptionConnector code
Fielddata.sessions[].operatorId Typenumber | null DescriptionIdentifier of the operator who finished the session. Employee: GET /v1/users
Fielddata.sessions[].userId Typenumber DescriptionInternal client identifier
Fielddata.sessions[].userCode Typestring DescriptionExternal client code in the connector
Fielddata.sessions[].chatId Typenumber DescriptionOpen Channel chat identifier. One chat goes through several sessions
Fielddata.sessions[].dateCreate Typestring DescriptionSession creation date, ISO 8601
Fielddata.sessions[].dateClose Typestring | null DescriptionSession closing date, ISO 8601
Fielddata.sessions[].dateFirstAnswer Typestring | null DescriptionFirst answer date, ISO 8601
Fielddata.sessions[].dateOperatorAnswer Typestring | null DescriptionDate when the operator started working on the session, ISO 8601. This is a different moment from dateFirstAnswer
Fielddata.sessions[].status Typestring DescriptionStatus: new / answered / closed / spam / paused
Fielddata.sessions[].closeReason Typestring | null DescriptionClose reason: operator / auto / spam / client / replyLimit
Fielddata.sessions[].vote Typestring DescriptionClient rating: like / dislike / none
Fielddata.sessions[].voteHead Typenumber | null DescriptionSupervisor rating. null if there is no rating or the user has no supervisor rating permission
Fielddata.sessions[].commentHead Typestring | null DescriptionSupervisor comment. null in the same cases as voteHead
Fielddata.sessions[].crmEntityType Typestring | null DescriptionType of the bound CRM entity, for example lead or deal. null if there is no binding or no read permission on the bound entity
Fielddata.sessions[].crmEntityId Typenumber | null DescriptionIdentifier of the bound CRM entity. To get the record, use the endpoint for its crmEntityType: lead GET /v1/leads/:id, deal GET /v1/deals/:id, contact GET /v1/contacts/:id, company GET /v1/companies/:id
Fielddata.sessions[].queueTransfers Typenumber DescriptionNumber of reassignments in the queue. The reassignments themselves: Reassignment history
Fielddata.sessions[].waitAnswer Typenumber | null DescriptionTime to first answer, seconds. A stored metric — do not compute it from the dates above, the values may differ
Fielddata.sessions[].waitClose Typenumber | null DescriptionTime to close, seconds. A stored metric, like waitAnswer
Fielddata.sessions[].kpiFirstAnswer Typeboolean | null DescriptionWhether the first-answer time target was met
Fielddata.sessions[].messageCount Typenumber DescriptionNumber of messages in the session
Fielddata.hasNextPage Typeboolean DescriptionWhether there is a next page

Response example

JSON 
{
  "success": true,
  "data": {
    "sessions": [
      {
        "id": 781,
        "configId": 1,
        "source": "livechat",
        "operatorId": 29,
        "userId": 1211,
        "userCode": "livechat|1|2073|1211",
        "chatId": 2075,
        "dateCreate": "2024-05-13T15:08:33+00:00",
        "dateClose": "2024-06-13T15:46:31+00:00",
        "dateFirstAnswer": "2024-05-13T15:12:05+00:00",
        "dateOperatorAnswer": "2024-05-13T15:09:14+00:00",
        "status": "closed",
        "closeReason": "operator",
        "vote": "like",
        "voteHead": null,
        "commentHead": null,
        "crmEntityType": "contact",
        "crmEntityId": 2399,
        "queueTransfers": 0,
        "waitAnswer": 212,
        "waitClose": 116,
        "kpiFirstAnswer": false,
        "messageCount": 5
      },
      {
        "id": 779,
        "configId": 1,
        "source": "livechat",
        "operatorId": 29,
        "userId": 1209,
        "userCode": "livechat|1|2069|1209",
        "chatId": 2071,
        "dateCreate": "2024-05-13T15:05:52+00:00",
        "dateClose": "2024-05-13T16:11:52+00:00",
        "dateFirstAnswer": "2024-05-13T15:06:50+00:00",
        "dateOperatorAnswer": "2024-05-13T15:06:41+00:00",
        "status": "closed",
        "closeReason": "operator",
        "vote": "none",
        "voteHead": null,
        "commentHead": null,
        "crmEntityType": "deal",
        "crmEntityId": 5317,
        "queueTransfers": 0,
        "waitAnswer": 58,
        "waitClose": 144,
        "kpiFirstAnswer": true,
        "messageCount": 2
      }
    ],
    "hasNextPage": false
  }
}

Error response example

422 — the period exceeds 1 year:

JSON 
{
  "success": false,
  "error": { "code": "BITRIX_ERROR", "message": "The requested period exceeds the maximum of 1 year", "b24Code": "PERIOD_TOO_LARGE" }
}

The error.message text is localized. To handle the error, check error.b24Code.

Errors

HTTP Code Description
HTTP400 CodeINVALID_JSON_BODY DescriptionThe request body could not be parsed as JSON. JSON is parsed before fields are checked, so the response says nothing about missing parameters
HTTP400 CodeINVALID_PARAMS DescriptionThe request body is not an object
HTTP422 CodeBITRIX_ERROR (error.b24Code: PERIOD_TOO_LARGE) DescriptionThe creation or closing period exceeds 1 year
HTTP422 CodeBITRIX_ERROR (error.b24Code: OFFSET_TOO_LARGE) Descriptionoffset exceeds the maximum — narrow the period or the filters
HTTP422 CodeBITRIX_ERROR (error.b24Code: INVALID_FILTER) DescriptionInvalid filter value, status and closeReason passed together, or kpiFirstAnswer without a bounded period
HTTP422 CodeMETHOD_NOT_YET_AVAILABLE DescriptionThe imopenlines 26.700.0 update has not reached the Bitrix24 account yet. The response contains an error.release field set to imopenlines 26.700.0
HTTP403 CodeB24_TARIFF_RESTRICTION DescriptionThe plan does not include Open Channel statistics (report_open_lines)
HTTP403 CodeSCOPE_DENIED DescriptionThe key has no imopenlines scope
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no configured tokens

Full list of common API errors: Errors.

See also