For AI agents: markdown of this page — /docs-content-en/bots/openlines.md documentation index — /llms.txt
Open Line 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.
| Action | Endpoint |
|---|---|
| Hand to an operator | POST /v1/bots/:botId/openlines/session/operator |
| Transfer | POST /v1/bots/:botId/openlines/session/transfer |
| Finish | POST /v1/bots/:botId/openlines/session/finish |
| Automatic message | POST /v1/bots/:botId/openlines/session/auto-message |
Handing a session to a person
Keep welcomeBotId in the line settings: it selects the bot that starts the conversation. Replace /v1/bots/:botId/chats/:dialogId/leave with .../session/operator to hand the session to an operator, or .../session/transfer with queueId for 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 after transfer; otherwise the bot stays. operator has no leave parameter. welcomeBotLeft: "queue" defines the departure point in the native scenario; its effect on an API-triggered transition is unverified, so use transfer with leave for explicit control.
Identifiers and permissions
botId is the numeric Bitrix24 identifier. Obtain chatId from event.data.chat.id or 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 that user, not an Open Line session. The CHAT_ID alias follows chatId and dialogId; null falls through, while a present malformed value produces 400.
Bitrix24 checks session permissions. Our ownership check applies to the addressed bot, not chat membership. All four actions and operator answer/finish share a portal limit of 30 requests per minute, divided by the active replica count per process.
Bot credentials stay on the server and are not input fields. CLIENT_ID is used internally only for webhook transfer/finish. On BOT_ID_ERROR the server tries the opposite composition once; other refusals are not retried.
Audit records successful calls and Bitrix24 refusals with key, bot, chat and transfer target identifiers. Automatic message text is not recorded. The addressed bot in audit is not proof of the bot identity resolved by Bitrix24 under OAuth.