# 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](./openlines/operator.md) | `POST /v1/bots/:botId/openlines/session/operator` |
| [Transfer](./openlines/transfer.md) | `POST /v1/bots/:botId/openlines/session/transfer` |
| [Finish](./openlines/finish.md) | `POST /v1/bots/:botId/openlines/session/finish` |
| [Automatic message](./openlines/auto-message.md) | `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.