For AI agents: markdown of this page — /docs-content-en/bots/openlines/operator.md documentation index — /llms.txt

Hand to an operator

POST /v1/bots/:botId/openlines/session/operator

Hands the Open Channel conversation from the bot to an available line operator. Call it when the bot cannot resolve the customer's question itself and the conversation needs to continue with an employee.

Parameters

Parameter Type Required Default Description
ParameterbotId (path) Typeinteger Requiredyes Default— DescriptionID of a bot registered with this key. List: GET /v1/bots

Request fields (body)

Field Type Required Description
FieldchatId Typeinteger | string Requiredyes DescriptionOpen Channel chat ID: a positive integer, a string of digits or the chat<N> form. Source: the data.chat.id field of a bot event or sessions[].chatId in POST /v1/openlines/sessions/search. Instead of chatId, you can pass dialogId or CHAT_ID
FielddialogId Typestring Requiredno DescriptionThe same chat, only in the chat<N> form, for example chat2043. A number without the prefix is not accepted here
FieldCHAT_ID Typeinteger | string Requiredno DescriptionAlternative name for chatId with the same formats

The first filled field is read, checking chatId, dialogId and CHAT_ID in that order. A field set to null counts as empty. An invalid value in the first filled field returns 400 INVALID_CHAT_ID, and the remaining fields are not checked in that case.

Examples

curl — personal key

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/bots/621/openlines/session/operator" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chatId": 2043}'

curl — OAuth application

Terminal 
curl -X POST "https://vibecode.bitrix24.com/v1/bots/621/openlines/session/operator" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"chatId": 2043}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/621/openlines/session/operator', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ chatId: 2043 }),
})

const { success, data, error } = await res.json()
console.log(success ? data.transferred : error.code)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/bots/621/openlines/session/operator', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ chatId: 2043 }),
})

const { success, data, error } = await res.json()
console.log(success ? data.transferred : error.code)

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue when Bitrix24 confirmed the call
Fielddata.chatId Typeinteger DescriptionID of the chat the action was applied to. Returned as a number even if the request passed the chat<N> form
Fielddata.transferred Typeboolean DescriptionAlways true in a successful response

Response example

JSON 
{
  "success": true,
  "data": {
    "chatId": 2043,
    "transferred": true
  }
}

Error response example

422 — Bitrix24 did not hand the conversation to an operator:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "Operator is not a bot",
    "b24Code": "WRONG_CHAT"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_BOT_ID DescriptionbotId in the path is not a positive integer
HTTP400 CodeINVALID_PARAMS DescriptionThe request body is not a JSON object, for example an array or a string
HTTP400 CodeINVALID_CHAT_ID DescriptionNone of the chatId, dialogId, CHAT_ID fields was passed, the value is invalid, or dialogId was passed without the chat prefix. A body that cannot be parsed as JSON is treated as empty and also gets this code. message says where to get the chat ID
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no portal tokens. For an application key, the user session token was not passed
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the imbot or imopenlines scope — both are required
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode
HTTP403 CodeBOT_ACCESS_DENIED DescriptionThe bot was registered by another key. To regain control, see Restoring access to a bot
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied access to the chat
HTTP404 CodeBOT_NOT_FOUND DescriptionNo bot with this botId on the portal — register it via POST /v1/bots
HTTP404 CodeENTITY_NOT_FOUND DescriptionBitrix24 reported that the record was not found
HTTP409 CodeBOT_ID_REPLACED DescriptionThe bot was registered again after the portal address changed. The new ID is in error.details.botId
HTTP409 CodeBOT_RECOVERY_IN_PROGRESS DescriptionThe bot is being restored automatically after the portal address changed. Retry after the pause from the Retry-After header
HTTP410 CodeBOT_DISABLED DescriptionThe bot is disabled. To bring the bot back, see Bot disabled
HTTP422 CodeBITRIX_ERROR Descriptionerror.b24Code is WRONG_CHAT, message is Operator is not a bot: the conversation was not handed over. The same response is returned for a nonexistent chatId
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the call for another reason. The Bitrix24 code is in error.b24Code
HTTP429 CodeRATE_LIMITED DescriptionThe shared platform ceiling of 30 requests per minute per portal was exceeded. The ceiling is shared by the four bot actions in an Open Channel and the POST /v1/openlines/operator/answer, POST /v1/openlines/operator/finish calls, and is split between platform replicas, so the code can arrive before the 30th request. The effective value is in the x-ratelimit-limit header, the time until a retry is in error.message. A request rejected with 400 because of an error in the body also counts against the limit
HTTP429 CodeRATE_LIMITED DescriptionBitrix24 throttled requests to the portal. Retry after the pause from the Retry-After header
HTTP429 CodeQUEUE_OVERFLOW DescriptionThe request queue to the portal is full. Retry after the pause from the Retry-After header
HTTP429 CodeQUEUE_TIMEOUT DescriptionThe request did not get its turn in the portal queue and was not sent to Bitrix24. Retry after the pause from the Retry-After header
HTTP502 CodeOPENLINE_BOT_SESSION_FAILED DescriptionBitrix24 did not confirm the handover: the call result is not true
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionThe Bitrix24 portal is unavailable
HTTP503 CodeBITRIX_TIMEOUT DescriptionThe Bitrix24 portal did not respond in time
HTTP503 Codeuser_self_deletion_pending DescriptionThe key owner's account on the portal is pending deletion

Full list of common API errors: Errors.

See also