[{"data":1,"prerenderedAt":11},["ShallowReactive",2],{"docs-bots\u002Fopenlines":3,"docs-tabs-bots\u002Fopenlines":6},{"content":4,"lastmod":5},"# Bot sessions in Open Channels\n\nA 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.\n\n## Handing a session to a person\n\nKeep `welcomeBotId` in the line settings: it selects the bot that starts the conversation. Instead of `\u002Fv1\u002Fbots\u002F:botId\u002Fchats\u002F:dialogId\u002Fleave`, call `...\u002Fsession\u002Foperator` to hand the session to an operator, or `...\u002Fsession\u002Ftransfer` with `queueId` to move it to a selected queue. `\u002Fleave` changes IM chat membership and does not move the session into the queue.\n\n`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.\n\n## Identifiers and permissions\n\n`botId` is the numeric Bitrix24 identifier returned by the [bot list](\u002Fdocs\u002Fbots\u002Fmanagement\u002Flist). Obtain `chatId` from `event.data.chat.id` or `sessions[].chatId` in [session search](\u002Fdocs\u002Fopenlines\u002Fsessions\u002Fsearch). A positive safe integer, numeric string or `chat\u003CN>` is accepted. `dialogId` accepts only `chat\u003CN>`: 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.\n\nBitrix24 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`\u002F`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`.\n\nBot credentials stay on the server and are not input fields. `CLIENT_ID` is used internally only for webhook `transfer`\u002F`finish`. On `BOT_ID_ERROR`, the server tries an alternative parameter combination once; other refusals are not retried.\n\nAudit 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.\n\n## Operations\n\n- [Hand to an operator](.\u002Fopenlines\u002Foperator.md) — `POST \u002Fv1\u002Fbots\u002F:botId\u002Fopenlines\u002Fsession\u002Foperator`\n- [Transfer](.\u002Fopenlines\u002Ftransfer.md) — `POST \u002Fv1\u002Fbots\u002F:botId\u002Fopenlines\u002Fsession\u002Ftransfer`\n- [Finish](.\u002Fopenlines\u002Ffinish.md) — `POST \u002Fv1\u002Fbots\u002F:botId\u002Fopenlines\u002Fsession\u002Ffinish`\n- [Automatic message](.\u002Fopenlines\u002Fauto-message.md) — `POST \u002Fv1\u002Fbots\u002F:botId\u002Fopenlines\u002Fsession\u002Fauto-message`\n\n## See also\n\n- [Open Channel sessions](\u002Fdocs\u002Fopenlines\u002Fsessions)\n- [Open Channels](\u002Fdocs\u002Fopenlines)\n- [Bot platform](\u002Fdocs\u002Fbots)\n","2026-10-23",{"openlines\u002Foperator.md":7,"openlines\u002Ftransfer.md":8,"openlines\u002Ffinish.md":9,"openlines\u002Fauto-message.md":10},"## Hand to an operator\n\n`POST \u002Fv1\u002Fbots\u002F:botId\u002Fopenlines\u002Fsession\u002Foperator`\n\nHands 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.\n\n## Parameters\n\n| Parameter | Type | Required | Default | Description |\n|----------|-----|:-----:|-----------|----------|\n| `botId` (path) | integer | yes | — | ID of a bot registered with this key. List: [`GET \u002Fv1\u002Fbots`](\u002Fdocs\u002Fbots\u002Fmanagement\u002Flist) |\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|----------|\n| `chatId` | integer \\| string | yes | Open Channel chat ID: a positive integer, a string of digits or the `chat\u003CN>` form. Source: the `data.chat.id` field of a [bot event](\u002Fdocs\u002Fbots\u002Fevents\u002Fbot-events) or `sessions[].chatId` in [`POST \u002Fv1\u002Fopenlines\u002Fsessions\u002Fsearch`](\u002Fdocs\u002Fopenlines\u002Fsessions\u002Fsearch). Instead of `chatId`, you can pass `dialogId` or `CHAT_ID` |\n| `dialogId` | string | no | The same chat, only in the `chat\u003CN>` form, for example `chat2043`. A number without the prefix is not accepted here |\n| `CHAT_ID` | integer \\| string | no | Alternative name for `chatId` with the same formats |\n\nThe 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.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fbots\u002F621\u002Fopenlines\u002Fsession\u002Foperator\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"chatId\": 2043}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fbots\u002F621\u002Fopenlines\u002Fsession\u002Foperator\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"chatId\": 2043}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fbots\u002F621\u002Fopenlines\u002Fsession\u002Foperator', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ chatId: 2043 }),\n})\n\nconst { success, data, error } = await res.json()\nconsole.log(success ? data.transferred : error.code)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fbots\u002F621\u002Fopenlines\u002Fsession\u002Foperator', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ chatId: 2043 }),\n})\n\nconst { success, data, error } = await res.json()\nconsole.log(success ? data.transferred : error.code)\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | `true` when Bitrix24 confirmed the call |\n| `data.chatId` | integer | ID of the chat the action was applied to. Returned as a number even if the request passed the `chat\u003CN>` form |\n| `data.transferred` | boolean | Always `true` in a successful response |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"chatId\": 2043,\n    \"transferred\": true\n  }\n}\n```\n\n## Error response example\n\n422 — Bitrix24 did not hand the conversation to an operator:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ERROR\",\n    \"message\": \"Operator is not a bot\",\n    \"b24Code\": \"WRONG_CHAT\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 400 | `INVALID_BOT_ID` | `botId` in the path is not a positive integer |\n| 400 | `INVALID_PARAMS` | The request body is not a JSON object, for example an array or a string |\n| 400 | `INVALID_CHAT_ID` | None 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 |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed |\n| 401 | `TOKEN_MISSING` | The key has no portal tokens. For an application key, the user session token was not passed |\n| 403 | `SCOPE_DENIED` | The key lacks the `imbot` or `imopenlines` scope — both are required |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode |\n| 403 | `BOT_ACCESS_DENIED` | The bot was registered by another key. To regain control, see [Restoring access to a bot](\u002Fdocs\u002Fbots\u002Fownership-recovery) |\n| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access to the chat |\n| 404 | `BOT_NOT_FOUND` | No bot with this `botId` on the portal — register it via `POST \u002Fv1\u002Fbots` |\n| 404 | `ENTITY_NOT_FOUND` | Bitrix24 reported that the record was not found |\n| 409 | `BOT_ID_REPLACED` | The bot was registered again after the portal address changed. The new ID is in `error.details.botId` |\n| 409 | `BOT_RECOVERY_IN_PROGRESS` | The bot is being restored automatically after the portal address changed. Retry after the pause from the `Retry-After` header |\n| 410 | `BOT_DISABLED` | The bot is disabled. To bring the bot back, see [Bot disabled](\u002Fdocs\u002Fbots\u002Ftroubleshooting#bot-disabled-bot_disabled) |\n| 422 | `BITRIX_ERROR` | `error.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` |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the call for another reason. The Bitrix24 code is in `error.b24Code` |\n| 429 | `RATE_LIMITED` | The 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 \u002Fv1\u002Fopenlines\u002Foperator\u002Fanswer`, `POST \u002Fv1\u002Fopenlines\u002Foperator\u002Ffinish` 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 |\n| 429 | `RATE_LIMITED` | Bitrix24 throttled requests to the portal. Retry after the pause from the `Retry-After` header |\n| 429 | `QUEUE_OVERFLOW` | The request queue to the portal is full. Retry after the pause from the `Retry-After` header |\n| 429 | `QUEUE_TIMEOUT` | The 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 |\n| 502 | `OPENLINE_BOT_SESSION_FAILED` | Bitrix24 did not confirm the handover: the call result is not `true` |\n| 502 | `BITRIX_UNAVAILABLE` | The Bitrix24 portal is unavailable |\n| 503 | `BITRIX_TIMEOUT` | The Bitrix24 portal did not respond in time |\n| 503 | `user_self_deletion_pending` | The key owner's account on the portal is pending deletion |\n\nFull list of common API errors: [Errors](\u002Fdocs\u002Ferrors).\n\n## See also\n\n- [Open Channel bot](\u002Fdocs\u002Fbots\u002Fopenlines)\n- [Transfer a session](\u002Fdocs\u002Fbots\u002Fopenlines\u002Ftransfer)\n- [Finish a session](\u002Fdocs\u002Fbots\u002Fopenlines\u002Ffinish)\n- [Session search](\u002Fdocs\u002Fopenlines\u002Fsessions\u002Fsearch)\n- [Bot events](\u002Fdocs\u002Fbots\u002Fevents\u002Fbot-events)\n","## Transfer a session\n\n`POST \u002Fv1\u002Fbots\u002F:botId\u002Fopenlines\u002Fsession\u002Ftransfer`\n\nThe bot transfers the Open Channel session to a selected employee or to a line queue. Call it instead of having the bot leave the chat when the conversation must move to a person in a given queue.\n\n## Parameters\n\n| Parameter | Type | Required | Default | Description |\n|----------|-----|:-----:|-----------|----------|\n| `botId` (path) | integer | yes | — | ID of a bot registered with this key. List: [`GET \u002Fv1\u002Fbots`](\u002Fdocs\u002Fbots\u002Fmanagement\u002Flist) |\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|----------|\n| `chatId` | integer \\| string | yes | Open Channel chat ID: a positive integer, a string of digits or the `chat\u003CN>` form. Source: the `data.chat.id` field of a [bot event](\u002Fdocs\u002Fbots\u002Fevents\u002Fbot-events) or `sessions[].chatId` in [`POST \u002Fv1\u002Fopenlines\u002Fsessions\u002Fsearch`](\u002Fdocs\u002Fopenlines\u002Fsessions\u002Fsearch). Instead of `chatId`, you can pass `dialogId` or `CHAT_ID` |\n| `dialogId` | string | no | The same chat, only in the `chat\u003CN>` form, for example `chat2043`. A number without the prefix is not accepted here |\n| `CHAT_ID` | integer \\| string | no | Alternative name for `chatId` with the same formats |\n| `userId` | integer \\| string | no | ID of the employee the session is transferred to: a positive integer or a string of digits. List: [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist) |\n| `queueId` | integer \\| string | no | ID of the line whose queue the session is transferred to: a positive integer or a string of digits. List: [`GET \u002Fv1\u002Fopenline-configs`](\u002Fdocs\u002Fopenlines\u002Fconfig\u002Flist) |\n| `transferId` | integer \\| string | no | Target as a single value: `queue\u003Cline ID>` is a line queue, for example `queue7`, with the prefix in any case. A number or a string of digits is an employee ID. Line ID from [`GET \u002Fv1\u002Fopenline-configs`](\u002Fdocs\u002Fopenlines\u002Fconfig\u002Flist), employee ID from [`GET \u002Fv1\u002Fusers`](\u002Fdocs\u002Fentities\u002Fusers\u002Flist) |\n| `leave` | boolean \\| string | no | Whether the bot leaves the chat after the transfer: `true`, `false`, `\"Y\"` or `\"N\"`. Without the field, the bot stays in the chat |\n\nThe first filled field among `chatId`, `dialogId` and `CHAT_ID` is read, in exactly this order. A field set to `null` counts as not filled. An invalid value in the first filled field returns `400 INVALID_CHAT_ID`, and the remaining fields are not checked in that case.\n\nPass exactly one of `userId`, `queueId` and `transferId`. A field set to `null` counts as not passed.\n\nTarget fields and `leave` are also accepted under uppercase names: `USER_ID`, `QUEUE_ID`, `TRANSFER_ID`, `LEAVE`. If both name variants are passed, the field with the name from the table above is read: `userId`, `queueId`, `transferId` or `leave`.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fbots\u002F621\u002Fopenlines\u002Fsession\u002Ftransfer \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"chatId\": 2043,\n    \"queueId\": 7,\n    \"leave\": true\n  }'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fbots\u002F621\u002Fopenlines\u002Fsession\u002Ftransfer \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"chatId\": 2043,\n    \"queueId\": 7,\n    \"leave\": true\n  }'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch(\n  'https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fbots\u002F621\u002Fopenlines\u002Fsession\u002Ftransfer',\n  {\n    method: 'POST',\n    headers: {\n      'X-Api-Key': 'YOUR_API_KEY',\n      'Content-Type': 'application\u002Fjson',\n    },\n    body: JSON.stringify({ chatId: 2043, queueId: 7, leave: true }),\n  }\n)\n\nconst { success, data, error } = await res.json()\nconsole.log(success ? data.transferred : error.code)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch(\n  'https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fbots\u002F621\u002Fopenlines\u002Fsession\u002Ftransfer',\n  {\n    method: 'POST',\n    headers: {\n      'X-Api-Key': 'YOUR_APP_KEY',\n      'Authorization': 'Bearer USER_SESSION_TOKEN',\n      'Content-Type': 'application\u002Fjson',\n    },\n    body: JSON.stringify({ chatId: 2043, queueId: 7, leave: true }),\n  }\n)\n\nconst { success, data, error } = await res.json()\nconsole.log(success ? data.transferred : error.code)\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | `true` when Bitrix24 confirmed the call |\n| `data.chatId` | integer | ID of the chat the action was applied to. Returned as a number even if the request passed the `chat\u003CN>` form |\n| `data.transferred` | boolean | Always `true`: Bitrix24 confirmed the transfer |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"chatId\": 2043,\n    \"transferred\": true\n  }\n}\n```\n\n## Error response example\n\n422 — Bitrix24 rejected the transfer:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BITRIX_ERROR\",\n    \"message\": \"You can not redirect to this operator\",\n    \"b24Code\": \"OPERATOR_WRONG\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 400 | `INVALID_BOT_ID` | `botId` in the path is not a positive integer |\n| 400 | `INVALID_PARAMS` | The request body is not a JSON object, for example an array or a string |\n| 400 | `INVALID_CHAT_ID` | None 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 |\n| 400 | `MISSING_TRANSFER_TARGET` | None of the `userId`, `queueId`, `transferId` fields was passed |\n| 400 | `INVALID_TRANSFER_TARGET` | More than one transfer target was passed |\n| 400 | `INVALID_TRANSFER_TARGET` | The target is neither a positive integer nor the `queue\u003CN>` form |\n| 400 | `INVALID_TRANSFER_TARGET` | `leave` is not one of `true`, `false`, `\"Y\"` or `\"N\"` |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed |\n| 401 | `TOKEN_MISSING` | The key has no portal tokens. For an application key, the user session token was not passed |\n| 403 | `SCOPE_DENIED` | The key lacks the `imbot` or `imopenlines` scope — both are required |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode |\n| 403 | `BOT_ACCESS_DENIED` | The bot was registered by another key. To regain control, see [Restoring access to a bot](\u002Fdocs\u002Fbots\u002Fownership-recovery) |\n| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access to the chat |\n| 404 | `BOT_NOT_FOUND` | No bot with this `botId` on the portal — register it via `POST \u002Fv1\u002Fbots` |\n| 404 | `ENTITY_NOT_FOUND` | Bitrix24 reported that the record was not found |\n| 409 | `BOT_ID_REPLACED` | The bot was registered again after the portal address changed. The new ID is in `error.details.botId` |\n| 409 | `BOT_RECOVERY_IN_PROGRESS` | The bot is being restored automatically after the portal address changed. Retry after the pause from the `Retry-After` header |\n| 410 | `BOT_DISABLED` | The bot is disabled. To bring the bot back, see [Bot disabled](\u002Fdocs\u002Fbots\u002Ftroubleshooting#bot-disabled-bot_disabled) |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the transfer. The Bitrix24 code is in `error.b24Code`, for example `OPERATOR_WRONG` |\n| 429 | `RATE_LIMITED` | The 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 \u002Fv1\u002Fopenlines\u002Foperator\u002Fanswer` and `POST \u002Fv1\u002Fopenlines\u002Foperator\u002Ffinish` 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, and 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 |\n| 429 | `RATE_LIMITED` | Bitrix24 throttled requests to the portal. Retry after the pause from the `Retry-After` header |\n| 429 | `QUEUE_OVERFLOW` | The request queue to the portal is full. Retry after the pause from the `Retry-After` header |\n| 429 | `QUEUE_TIMEOUT` | The 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 |\n| 502 | `OPENLINE_BOT_SESSION_FAILED` | Bitrix24 did not confirm the transfer: the call result is not `true` |\n| 502 | `BITRIX_UNAVAILABLE` | The Bitrix24 portal is unavailable |\n| 503 | `BITRIX_TIMEOUT` | The Bitrix24 portal did not respond in time |\n| 503 | `user_self_deletion_pending` | The key owner's account on the portal is pending deletion |\n\nFull list of common API errors: [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**`OPERATOR_WRONG` does not distinguish a wrong target from a wrong chat.** A transfer to an existing queue or an existing employee, but in a chat that does not exist, also returns `422 BITRIX_ERROR` with `error.b24Code` equal to `OPERATOR_WRONG`. Check `chatId` against the bot event or [session search](\u002Fdocs\u002Fopenlines\u002Fsessions\u002Fsearch) before changing the target.\n\n## See also\n\n- [Open Channel bot](\u002Fdocs\u002Fbots\u002Fopenlines)\n- [Hand to an operator](\u002Fdocs\u002Fbots\u002Fopenlines\u002Foperator)\n- [Finish a session](\u002Fdocs\u002Fbots\u002Fopenlines\u002Ffinish)\n- [Send an automatic line message](\u002Fdocs\u002Fbots\u002Fopenlines\u002Fauto-message)\n- [List of Open Channel configurations](\u002Fdocs\u002Fopenlines\u002Fconfig\u002Flist)\n","## Finish a session\n\n`POST \u002Fv1\u002Fbots\u002F:botId\u002Fopenlines\u002Fsession\u002Ffinish`\n\nFinishes the current Open Channel session on behalf of the bot that runs the conversation. Call it when the bot has resolved the customer's question itself and the conversation does not need to go to an operator.\n\n## Parameters\n\n| Parameter | Type | Required | Default | Description |\n|----------|-----|:-----:|-----------|----------|\n| `botId` (path) | integer | yes | — | ID of a bot registered with this key. List: [`GET \u002Fv1\u002Fbots`](\u002Fdocs\u002Fbots\u002Fmanagement\u002Flist) |\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|----------|\n| `chatId` | integer \\| string | yes | Open Channel chat ID: a positive integer, a string of digits or the `chat\u003CN>` form. Source: the `data.chat.id` field of a [bot event](\u002Fdocs\u002Fbots\u002Fevents\u002Fbot-events) or `sessions[].chatId` in [`POST \u002Fv1\u002Fopenlines\u002Fsessions\u002Fsearch`](\u002Fdocs\u002Fopenlines\u002Fsessions\u002Fsearch). Instead of `chatId`, you can pass `dialogId` or `CHAT_ID` |\n| `dialogId` | string | no | The same chat, only in the `chat\u003CN>` form, for example `chat2043`. A number without the prefix is not accepted here |\n| `CHAT_ID` | integer \\| string | no | Alternative name for `chatId` with the same formats |\n\nThe first of `chatId`, `dialogId` and `CHAT_ID` that is set is read, checked in exactly this order. A field set to `null` counts as not set. An invalid value in the first filled field returns `400 INVALID_CHAT_ID`, and the remaining fields are not checked in that case.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fbots\u002F621\u002Fopenlines\u002Fsession\u002Ffinish\" \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"chatId\": 2043}'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST \"https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fbots\u002F621\u002Fopenlines\u002Fsession\u002Ffinish\" \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"chatId\": 2043}'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fbots\u002F621\u002Fopenlines\u002Fsession\u002Ffinish', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_API_KEY',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ chatId: 2043 }),\n})\n\nconst { success, data, error } = await res.json()\nconsole.log(success ? data.finished : error.code)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch('https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fbots\u002F621\u002Fopenlines\u002Fsession\u002Ffinish', {\n  method: 'POST',\n  headers: {\n    'X-Api-Key': 'YOUR_APP_KEY',\n    'Authorization': 'Bearer USER_SESSION_TOKEN',\n    'Content-Type': 'application\u002Fjson',\n  },\n  body: JSON.stringify({ chatId: 2043 }),\n})\n\nconst { success, data, error } = await res.json()\nconsole.log(success ? data.finished : error.code)\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | `true` when Bitrix24 confirmed the call |\n| `data.chatId` | integer | ID of the chat the action was applied to. Returned as a number even if the request passed the `chat\u003CN>` form |\n| `data.finished` | boolean | Always `true` in a successful response |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"chatId\": 2043,\n    \"finished\": true\n  }\n}\n```\n\n## Error response example\n\n404 — no bot with this `botId` on the Bitrix24 account:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"BOT_NOT_FOUND\",\n    \"message\": \"Bot 999999 not found. Register it first via POST \u002Fv1\u002Fbots.\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 400 | `INVALID_BOT_ID` | `botId` in the path is not a positive integer |\n| 400 | `INVALID_PARAMS` | The request body is not a JSON object, for example an array or a string |\n| 400 | `INVALID_CHAT_ID` | None 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 |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed |\n| 401 | `TOKEN_MISSING` | The key has no portal tokens. For an application key, the user session token was not passed |\n| 403 | `SCOPE_DENIED` | The key lacks the `imbot` or `imopenlines` scope — both are required |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode |\n| 403 | `BOT_ACCESS_DENIED` | The bot was registered by another key. To regain control, see [Restoring access to a bot](\u002Fdocs\u002Fbots\u002Fownership-recovery) |\n| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access to the chat |\n| 404 | `BOT_NOT_FOUND` | No bot with this `botId` on the portal — register it via `POST \u002Fv1\u002Fbots` |\n| 404 | `ENTITY_NOT_FOUND` | Bitrix24 reported that the record was not found |\n| 409 | `BOT_ID_REPLACED` | The bot was registered again after the portal address changed. The new ID is in `error.details.botId` |\n| 409 | `BOT_RECOVERY_IN_PROGRESS` | The bot is being restored automatically after the portal address changed. Retry after the pause from the `Retry-After` header |\n| 410 | `BOT_DISABLED` | The bot is disabled. To bring the bot back, see [Bot disabled](\u002Fdocs\u002Fbots\u002Ftroubleshooting#bot-disabled-bot_disabled) |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the call. The Bitrix24 code is in `error.b24Code`, for example `BOT_ID_ERROR` |\n| 429 | `RATE_LIMITED` | The shared platform ceiling of 30 requests per minute per portal was exceeded. The ceiling is shared by the four Open Channel bot actions and the `POST \u002Fv1\u002Fopenlines\u002Foperator\u002Fanswer` and `POST \u002Fv1\u002Fopenlines\u002Foperator\u002Ffinish` 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, and 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 |\n| 429 | `RATE_LIMITED` | Bitrix24 throttled requests to the portal. Retry after the pause from the `Retry-After` header |\n| 429 | `QUEUE_OVERFLOW` | The request queue to the portal is full. Retry after the pause from the `Retry-After` header |\n| 429 | `QUEUE_TIMEOUT` | The 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 |\n| 502 | `OPENLINE_BOT_SESSION_FAILED` | Bitrix24 did not confirm the finish: the call result is not `true` |\n| 502 | `BITRIX_UNAVAILABLE` | The Bitrix24 portal is unavailable |\n| 503 | `BITRIX_TIMEOUT` | The Bitrix24 portal did not respond in time |\n| 503 | `user_self_deletion_pending` | The key owner's account on the portal is pending deletion |\n\nFull list of common API errors: [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**`finished: true` does not prove that a session existed.** A `200` response with `finished: true` also arrives when there is nothing to finish, for example for a nonexistent `chatId`. To make sure the session is closed, check the `status` and `dateClose` fields of the session in [`POST \u002Fv1\u002Fopenlines\u002Fsessions\u002Fsearch`](\u002Fdocs\u002Fopenlines\u002Fsessions\u002Fsearch).\n\n## See also\n\n- [Open Channel bot](\u002Fdocs\u002Fbots\u002Fopenlines)\n- [Hand to an operator](\u002Fdocs\u002Fbots\u002Fopenlines\u002Foperator)\n- [Transfer a session](\u002Fdocs\u002Fbots\u002Fopenlines\u002Ftransfer)\n- [Session search](\u002Fdocs\u002Fopenlines\u002Fsessions\u002Fsearch)\n- [Bot events](\u002Fdocs\u002Fbots\u002Fevents\u002Fbot-events)\n","## Send an automatic line message\n\n`POST \u002Fv1\u002Fbots\u002F:botId\u002Fopenlines\u002Fsession\u002Fauto-message`\n\nThe bot sends either the welcome message from the Open Channel settings or a system message with the given text to the Open Channel conversation. To reply to the customer on behalf of the bot, use a different method: [Send message](\u002Fdocs\u002Fbots\u002Fmessages\u002Fsend).\n\n## Parameters\n\n| Parameter | Type | Required | Default | Description |\n|----------|-----|:-----:|-----------|----------|\n| `botId` (path) | integer | yes | — | ID of a bot registered with this key. List: [`GET \u002Fv1\u002Fbots`](\u002Fdocs\u002Fbots\u002Fmanagement\u002Flist) |\n\n## Request fields (body)\n\n| Field | Type | Required | Description |\n|------|-----|:-----:|----------|\n| `chatId` | integer \\| string | yes | Open Channel chat ID: a positive integer, a string of digits or the `chat\u003CN>` form. Source: the `data.chat.id` field of a [bot event](\u002Fdocs\u002Fbots\u002Fevents\u002Fbot-events) or `sessions[].chatId` in [`POST \u002Fv1\u002Fopenlines\u002Fsessions\u002Fsearch`](\u002Fdocs\u002Fopenlines\u002Fsessions\u002Fsearch). Instead of `chatId`, you can pass `dialogId` or `CHAT_ID` |\n| `dialogId` | string | no | The same chat, only in the `chat\u003CN>` form, for example `chat2043`. A number without the prefix is not accepted here |\n| `CHAT_ID` | integer \\| string | no | Alternative name for `chatId` with the same formats |\n| `type` | string | yes | Automatic message type: `WELCOME` is the welcome message from the Open Channel settings, `DEFAULT` is a system message with the text from `message` |\n| `message` | string | no | Message text. Required with `type: \"DEFAULT\"`, and in that case an empty string and the string `\"0\"` are not accepted |\n\nOf `chatId`, `dialogId` and `CHAT_ID`, the first field that is set is used, checked in exactly this order. A field set to `null` counts as not set. An invalid value in the first set field returns `400 INVALID_CHAT_ID`, and the remaining fields are not checked in that case.\n\n## Examples\n\n### curl — personal key\n\n```bash\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fbots\u002F621\u002Fopenlines\u002Fsession\u002Fauto-message \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"chatId\": 2043,\n    \"type\": \"DEFAULT\",\n    \"message\": \"Thank you for reaching out! We will reply within 10 minutes.\"\n  }'\n```\n\n### curl — OAuth application\n\n```bash\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fbots\u002F621\u002Fopenlines\u002Fsession\u002Fauto-message \\\n  -H \"X-Api-Key: YOUR_APP_KEY\" \\\n  -H \"Authorization: Bearer USER_SESSION_TOKEN\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"chatId\": 2043,\n    \"type\": \"DEFAULT\",\n    \"message\": \"Thank you for reaching out! We will reply within 10 minutes.\"\n  }'\n```\n\n### JavaScript — personal key\n\n```javascript\nconst res = await fetch(\n  'https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fbots\u002F621\u002Fopenlines\u002Fsession\u002Fauto-message',\n  {\n    method: 'POST',\n    headers: {\n      'X-Api-Key': 'YOUR_API_KEY',\n      'Content-Type': 'application\u002Fjson',\n    },\n    body: JSON.stringify({\n      chatId: 2043,\n      type: 'DEFAULT',\n      message: 'Thank you for reaching out! We will reply within 10 minutes.',\n    }),\n  }\n)\n\nconst { success, data, error } = await res.json()\nconsole.log(success ? data.accepted : error.code)\n```\n\n### JavaScript — OAuth application\n\n```javascript\nconst res = await fetch(\n  'https:\u002F\u002Fvibecode.bitrix24.com\u002Fv1\u002Fbots\u002F621\u002Fopenlines\u002Fsession\u002Fauto-message',\n  {\n    method: 'POST',\n    headers: {\n      'X-Api-Key': 'YOUR_APP_KEY',\n      'Authorization': 'Bearer USER_SESSION_TOKEN',\n      'Content-Type': 'application\u002Fjson',\n    },\n    body: JSON.stringify({\n      chatId: 2043,\n      type: 'DEFAULT',\n      message: 'Thank you for reaching out! We will reply within 10 minutes.',\n    }),\n  }\n)\n\nconst { success, data, error } = await res.json()\nconsole.log(success ? data.accepted : error.code)\n```\n\n## Response fields\n\n| Field | Type | Description |\n|------|-----|----------|\n| `success` | boolean | `true` when Bitrix24 confirmed the call |\n| `data.chatId` | integer | ID of the chat the action was applied to. Returned as a number even if the request passed the `chat\u003CN>` form |\n| `data.accepted` | boolean | Always `true`: Bitrix24 accepted the call. The field does not confirm delivery of the message to the customer |\n\n## Response example\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"chatId\": 2043,\n    \"accepted\": true\n  }\n}\n```\n\n## Error response example\n\n400 — `type: \"DEFAULT\"` was passed without message text:\n\n```json\n{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"MISSING_REQUIRED_FIELDS\",\n    \"message\": \"DEFAULT requires a non-empty message other than \\\"0\\\"\"\n  }\n}\n```\n\n## Errors\n\n| HTTP | Code | Description |\n|------|-----|----------|\n| 400 | `INVALID_BOT_ID` | `botId` in the path is not a positive integer |\n| 400 | `INVALID_PARAMS` | The request body is not a JSON object, for example an array or a string |\n| 400 | `INVALID_PARAMS` | `type` is neither `WELCOME` nor `DEFAULT` |\n| 400 | `INVALID_PARAMS` | With `type: \"WELCOME\"`, the `message` field is not a string |\n| 400 | `INVALID_CHAT_ID` | None 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 |\n| 400 | `MISSING_REQUIRED_FIELDS` | With `type: \"DEFAULT\"`, `message` is missing, is not a string, or is an empty string or `\"0\"` |\n| 401 | `MISSING_API_KEY` | The `X-Api-Key` header was not passed |\n| 401 | `TOKEN_MISSING` | The key has no portal tokens. For an application key, the user session token was not passed |\n| 403 | `SCOPE_DENIED` | The key lacks the `imbot` or `imopenlines` scope — both are required |\n| 403 | `WRITE_BLOCKED_READONLY_KEY` | The key is in read-only mode |\n| 403 | `BOT_ACCESS_DENIED` | The bot was registered by another key. To regain control, see [Restoring access to a bot](\u002Fdocs\u002Fbots\u002Fownership-recovery) |\n| 403 | `BITRIX_ACCESS_DENIED` | Bitrix24 denied access to the chat |\n| 404 | `BOT_NOT_FOUND` | There is no bot with this `botId` on the portal — register it via `POST \u002Fv1\u002Fbots` |\n| 404 | `ENTITY_NOT_FOUND` | Bitrix24 reported that the record was not found |\n| 409 | `BOT_ID_REPLACED` | The bot was registered again after the portal address changed. The new ID is in `error.details.botId` |\n| 409 | `BOT_RECOVERY_IN_PROGRESS` | The bot is being restored automatically after the portal address changed. Retry after the delay given in the `Retry-After` header |\n| 410 | `BOT_DISABLED` | The bot is disabled. To bring the bot back, see [Bot disabled](\u002Fdocs\u002Fbots\u002Ftroubleshooting#bot-disabled-bot_disabled) |\n| 422 | `BITRIX_ERROR` | Bitrix24 rejected the call. The Bitrix24 code is in `error.b24Code` |\n| 429 | `RATE_LIMITED` | The 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 \u002Fv1\u002Fopenlines\u002Foperator\u002Fanswer` and `POST \u002Fv1\u002Fopenlines\u002Foperator\u002Ffinish` 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 |\n| 429 | `RATE_LIMITED` | Bitrix24 throttled requests to the portal. Retry after the delay given in the `Retry-After` header |\n| 429 | `QUEUE_OVERFLOW` | The request queue to the portal is full. Retry after the delay given in the `Retry-After` header |\n| 429 | `QUEUE_TIMEOUT` | The request did not get its turn in the portal queue and was not sent to Bitrix24. Retry after the delay given in the `Retry-After` header |\n| 502 | `OPENLINE_BOT_SESSION_FAILED` | Bitrix24 did not confirm the call: the call result is not `true` |\n| 502 | `BITRIX_UNAVAILABLE` | The Bitrix24 portal is unavailable |\n| 503 | `BITRIX_TIMEOUT` | The Bitrix24 portal did not respond in time |\n| 503 | `user_self_deletion_pending` | The key owner's account on the portal is pending deletion |\n\nFull list of common API errors: [Errors](\u002Fdocs\u002Ferrors).\n\n## Known specifics\n\n**`accepted: true` does not mean the message was sent.** A `200` response with `accepted: true` also arrives when the message was not added to the chat, for example if there is no chat with this `chatId`.\n\n## See also\n\n- [Open Channel bot](\u002Fdocs\u002Fbots\u002Fopenlines)\n- [Hand to an operator](\u002Fdocs\u002Fbots\u002Fopenlines\u002Foperator)\n- [Transfer a session](\u002Fdocs\u002Fbots\u002Fopenlines\u002Ftransfer)\n- [Finish a session](\u002Fdocs\u002Fbots\u002Fopenlines\u002Ffinish)\n- [Send message](\u002Fdocs\u002Fbots\u002Fmessages\u002Fsend)\n",1795000414353]