# Bot sessions in Open Channels

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 after transfer; otherwise the bot stays. `operator` has no `leave` parameter. `welcomeBotLeft: "queue"` determines when the bot leaves in the native workflow; 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 returned by the [bot list](/docs/bots/management/list). Obtain `chatId` from `event.data.chat.id` or `sessions[].chatId` in [session search](/docs/openlines/sessions/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 an employee, not a session in Open Channels. 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 bot specified in the path, not to ownership of the chat. All four actions and operator `answer`/`finish` share a limit of 30 requests per minute per Bitrix24 account. The `x-ratelimit-limit` header reports this route limiter’s effective limit. The shared key or owner limit also applies; a `CALLER_RATE_LIMITED` response supplies `Retry-After` and `X-RateLimit-Scope`.

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 an alternative parameter combination 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 bot recorded in the audit log does not necessarily match the bot Bitrix24 resolves under OAuth.

## Operations

- [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`

## See also

- [Open Channel sessions](/docs/openlines/sessions)
- [Open Channels](/docs/openlines)
- [Bot platform](/docs/bots)