Dành cho AI agent: markdown của trang này — /docs-content-en/openlines/operator.md chỉ mục tài liệu — /llms.txt
Hiện tại, các bài viết trong tài liệu chỉ có bằng tiếng Anh.
Operator actions and my pause
Actions on an Open Channel dialog on behalf of the employee the key belongs to: skip a dialog, transfer it, mark the client as spam, finish another operator's dialog. This section also covers reading, starting and stopping your own operator pause.
Bitrix24 API: imopenlines.operator.*
Scope: imopenlines
On whose behalf the action runs
These methods take no employee parameter. The action and the pause apply to the employee the call runs as:
| Authorization | Employee |
|---|---|
AuthorizationPersonal key (X-Api-Key: YOUR_API_KEY) |
EmployeeThe key owner |
AuthorizationOAuth application (X-Api-Key: YOUR_APP_KEY + Authorization: Bearer USER_SESSION_TOKEN) |
EmployeeThe user whose session is passed in Authorization |
Permissions for the action are checked against this employee. Every method except reading the pause requires a key with write access.
Chat ID
The methods take chatId, the numeric ID of the Open Channel chat, for example 5255. It is not a dialogId such as chat5255 and not a sessionId. One chat goes through several sessions, and the action applies to the chat's current session.
Where to get chatId:
- The
chatIdfield in thePOST /v1/openlines/sessions/searchresponse. POST /v1/openlines/sessions/open— by the client's code in the connector.GET /v1/openlines/crm/chats— by a CRM card.
Typical scenario
- Find the client's chat:
POST /v1/openlines/sessions/searchby channel, orPOST /v1/openlines/sessions/openby the client's code. - Take the dialog yourself:
POST /v1/openlines/sessions/start. The employee the call runs as becomes the session operator. - Transfer the dialog to a colleague or to the channel queue:
POST /v1/openlines/operator/transfer. - Finish a dialog that another operator is handling:
POST /v1/openlines/operator/finish-another.
Skip a dialog
POST /v1/openlines/operator/skip
Declines an Open Channel dialog offered to the employee: the dialog returns to the channel queue.
The action runs on behalf of the employee the key belongs to — see On whose behalf the action runs.
Request fields (body)
| Field | Type | Required | Description |
|---|---|---|---|
FieldchatId |
Typenumber | string | Requiredyes | DescriptionOpen Channel chat identifier, a positive integer. A string is accepted if it consists of digits only and does not start with zero. See Chat ID |
Examples
curl — personal key
curl -X POST https://vibecode.bitrix24.com/v1/openlines/operator/skip \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"chatId": 5255}'
curl — OAuth application
curl -X POST https://vibecode.bitrix24.com/v1/openlines/operator/skip \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"chatId": 5255}'
JavaScript — personal key
const res = await fetch('https://vibecode.bitrix24.com/v1/openlines/operator/skip', {
method: 'POST',
headers: {
'X-Api-Key': 'YOUR_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({ chatId: 5255 }),
})
const body = await res.json()
if (!body.success) throw new Error(`${body.error.code}: ${body.error.message}`)
console.log('Dialog skipped:', body.data.chatId)
JavaScript — OAuth application
const res = await fetch('https://vibecode.bitrix24.com/v1/openlines/operator/skip', {
method: 'POST',
headers: {
'X-Api-Key': 'YOUR_APP_KEY',
'Authorization': 'Bearer USER_SESSION_TOKEN',
'Content-Type': 'application/json',
},
body: JSON.stringify({ chatId: 5255 }),
})
const body = await res.json()
if (!body.success) throw new Error(`${body.error.code}: ${body.error.message}`)
console.log('Dialog skipped:', body.data.chatId)
Response fields
| Field | Type | Description |
|---|---|---|
Fieldsuccess |
Typeboolean | Descriptiontrue |
Fielddata.chatId |
Typenumber | DescriptionChat identifier from the request. A string from the request is returned as a number |
Fielddata.skipped |
Typeboolean | DescriptionAlways true |
Response example
{
"success": true,
"data": {
"chatId": 5255,
"skipped": true
}
}
Error response example
404 — no chat with this identifier:
{
"success": false,
"error": {
"code": "ENTITY_NOT_FOUND",
"message": "Open Line chat not found"
}
}
Errors
| HTTP | Code | Description |
|---|---|---|
| HTTP400 | CodeINVALID_CHAT_ID |
DescriptionchatId is missing, is not a positive integer, is a string with non-digit characters or a leading zero, or is greater than 9007199254740991 |
| HTTP404 | CodeENTITY_NOT_FOUND |
DescriptionNo chat with this chatId |
| HTTP422 | CodeBITRIX_ERROR |
DescriptionThe dialog has already been accepted by an operator — the employee the call runs as or another employee. error.message is Bitrix24 API error: 400, and there is no error.b24Code field. To hand an accepted dialog to a colleague or to the queue, use POST /v1/openlines/operator/transfer |
| HTTP422 | CodeBITRIX_ERROR |
DescriptionThe chat has no open session: the dialog is already finished. error.b24Code is ACCESS_DENIED_KICK, and error.message is in the portal language |
| HTTP403 | CodeBITRIX_ACCESS_DENIED |
DescriptionThe employee the call runs as has no permission for the action |
| HTTP502 | CodeOPENLINE_OPERATOR_FAILED |
DescriptionBitrix24 responded without an error but did not confirm the action |
| HTTP403 | CodeSCOPE_DENIED |
DescriptionThe key has no imopenlines scope |
| HTTP403 | CodeWRITE_BLOCKED_READONLY_KEY |
DescriptionThe key is read-only |
| HTTP401 | CodeMISSING_API_KEY |
DescriptionThe X-Api-Key header is missing |
| HTTP401 | CodeINVALID_API_KEY |
DescriptionThe key is not recognized |
| HTTP401 | CodeTOKEN_MISSING |
DescriptionA personal key has no access to the Bitrix24 portal, or an application key was sent without a session token in Authorization |
| HTTP502 | CodeBITRIX_UNAVAILABLE |
DescriptionBitrix24 is unavailable or the connection to it broke before the response was complete |
Full list of common API errors — Errors.