Open Channel bot sessions

A bot can hand a session to an operator, transfer it to a selected queue, finish it or request an automatic line message. Both imbot and imopenlines scopes and the key owning the bot are required. READONLY keys cannot perform these actions.

Handing a session to a person

Keep welcomeBotId in the line settings: it selects the bot that starts the conversation. Instead of /v1/bots/:botId/chats/:dialogId/leave, call .../session/operator to hand the session to an operator, or .../session/transfer with queueId to move it to a selected queue. /leave changes IM chat membership and does not move the session into the queue.

transfer accepts explicit leave: true to remove the bot from the chat after the transfer. Without it, the bot stays. operator has no leave parameter. welcomeBotLeft: "queue" defines when the bot leaves in a line scenario without API calls. For a controlled exit after a transfer through the API, use transfer with leave: true.

Identifiers and permissions

botId is the numeric bot identifier in Bitrix24, returned by the bot list. Obtain chatId from event.data.chat.id or from sessions[].chatId in session search. A positive safe integer, numeric string or chat<N> is accepted. dialogId accepts only chat<N>: a bare number means a private dialog with a user, not an Open Channel session. The CHAT_ID alias is read after chatId and dialogId. A null value is skipped, and a present malformed value produces 400.

Bitrix24 checks session permissions. Our ownership check applies to the bot in the path, not to chat ownership. All four actions and operator answer/finish share a limit of 30 requests per minute per Bitrix24 account. The per-process limit is divided by the number of active replicas.

Bot credentials stay on the server and do not need to be passed in the request. CLIENT_ID is used internally only for webhook transfer/finish. On BOT_ID_ERROR in transfer and finish, the server repeats the call once with a different set of bot credentials. Other refusals are not retried.

The audit records successful calls and Bitrix24 refusals with key, bot, chat and transfer target identifiers. Automatic message text is not recorded. The bot from the path recorded in the audit does not guarantee that, under OAuth authorization, Bitrix24 performed the action as that bot.

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

Request fields (body)

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

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

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

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

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

Response example

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

Error response example

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

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

Errors

Full list of common API errors: Errors.

See also

• Open Channel bot
• Transfer a session
• Finish a session
• Session search
• Bot events