[{"data":1,"prerenderedAt":7},["ShallowReactive",2],{"docs-bots\u002Fopenlines\u002Ftransfer":3,"docs-tabs-bots\u002Fopenlines\u002Ftransfer":6},{"content":4,"lastmod":5},"## 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","2026-10-19",{},1795000414945]