For AI agents: markdown of this page — /docs-content-en/bots/openlines/transfer.md documentation index — /llms.txt

Transfer a session

POST /v1/bots/:botId/openlines/session/transfer

The 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.

Parameters

Parameter Type Required Default Description
ParameterbotId (path) Typeinteger Requiredyes Default— DescriptionID of a bot registered with this key. List: GET /v1/bots

Request fields (body)

Field Type Required Description
FieldchatId Typeinteger | string Requiredyes DescriptionOpen Channel chat ID: a positive integer, a string of digits or the chat<N> form. Source: the data.chat.id field of a bot event or sessions[].chatId in POST /v1/openlines/sessions/search. Instead of chatId, you can pass dialogId or CHAT_ID
FielddialogId Typestring Requiredno DescriptionThe same chat, only in the chat<N> form, for example chat2043. A number without the prefix is not accepted here
FieldCHAT_ID Typeinteger | string Requiredno DescriptionAlternative name for chatId with the same formats
FielduserId Typeinteger | string Requiredno DescriptionID of the employee the session is transferred to: a positive integer or a string of digits. List: GET /v1/users
FieldqueueId Typeinteger | string Requiredno DescriptionID of the line whose queue the session is transferred to: a positive integer or a string of digits. List: GET /v1/openline-configs
FieldtransferId Typeinteger | string Requiredno DescriptionTarget as a single value: queue<line 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 /v1/openline-configs, employee ID from GET /v1/users
Fieldleave Typeboolean | string Requiredno DescriptionWhether the bot leaves the chat after the transfer: true, false, "Y" or "N". Without the field, the bot stays in the chat

The 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.

Pass exactly one of userId, queueId and transferId. A field set to null counts as not passed.

Target 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.

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/bots/621/openlines/session/transfer \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": 2043,
    "queueId": 7,
    "leave": true
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/bots/621/openlines/session/transfer \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": 2043,
    "queueId": 7,
    "leave": true
  }'

JavaScript — personal key

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/bots/621/openlines/session/transfer',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ chatId: 2043, queueId: 7, leave: true }),
  }
)

const { success, data, error } = await res.json()
console.log(success ? data.transferred : error.code)

JavaScript — OAuth application

javascript 
const res = await fetch(
  'https://vibecode.bitrix24.com/v1/bots/621/openlines/session/transfer',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ chatId: 2043, queueId: 7, leave: true }),
  }
)

const { success, data, error } = await res.json()
console.log(success ? data.transferred : error.code)

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue when Bitrix24 confirmed the call
Fielddata.chatId Typeinteger DescriptionID of the chat the action was applied to. Returned as a number even if the request passed the chat<N> form
Fielddata.transferred Typeboolean DescriptionAlways true: Bitrix24 confirmed the transfer

Response example

JSON 
{
  "success": true,
  "data": {
    "chatId": 2043,
    "transferred": true
  }
}

Error response example

422 — Bitrix24 rejected the transfer:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "You can not redirect to this operator",
    "b24Code": "OPERATOR_WRONG"
  }
}

Errors

HTTP Code Description
HTTP400 CodeINVALID_BOT_ID DescriptionbotId in the path is not a positive integer
HTTP400 CodeINVALID_PARAMS DescriptionThe request body is not a JSON object, for example an array or a string
HTTP400 CodeINVALID_CHAT_ID DescriptionNone 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
HTTP400 CodeMISSING_TRANSFER_TARGET DescriptionNone of the userId, queueId, transferId fields was passed
HTTP400 CodeINVALID_TRANSFER_TARGET DescriptionMore than one transfer target was passed
HTTP400 CodeINVALID_TRANSFER_TARGET DescriptionThe target is neither a positive integer nor the queue<N> form
HTTP400 CodeINVALID_TRANSFER_TARGET Descriptionleave is not one of true, false, "Y" or "N"
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no portal tokens. For an application key, the user session token was not passed
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the imbot or imopenlines scope — both are required
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode
HTTP403 CodeBOT_ACCESS_DENIED DescriptionThe bot was registered by another key. To regain control, see Restoring access to a bot
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied access to the chat
HTTP404 CodeBOT_NOT_FOUND DescriptionNo bot with this botId on the portal — register it via POST /v1/bots
HTTP404 CodeENTITY_NOT_FOUND DescriptionBitrix24 reported that the record was not found
HTTP409 CodeBOT_ID_REPLACED DescriptionThe bot was registered again after the portal address changed. The new ID is in error.details.botId
HTTP409 CodeBOT_RECOVERY_IN_PROGRESS DescriptionThe bot is being restored automatically after the portal address changed. Retry after the pause from the Retry-After header
HTTP410 CodeBOT_DISABLED DescriptionThe bot is disabled. To bring the bot back, see Bot disabled
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the transfer. The Bitrix24 code is in error.b24Code, for example OPERATOR_WRONG
HTTP429 CodeRATE_LIMITED DescriptionThe 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 /v1/openlines/operator/answer and POST /v1/openlines/operator/finish 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
HTTP429 CodeRATE_LIMITED DescriptionBitrix24 throttled requests to the portal. Retry after the pause from the Retry-After header
HTTP429 CodeQUEUE_OVERFLOW DescriptionThe request queue to the portal is full. Retry after the pause from the Retry-After header
HTTP429 CodeQUEUE_TIMEOUT DescriptionThe 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
HTTP502 CodeOPENLINE_BOT_SESSION_FAILED DescriptionBitrix24 did not confirm the transfer: the call result is not true
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionThe Bitrix24 portal is unavailable
HTTP503 CodeBITRIX_TIMEOUT DescriptionThe Bitrix24 portal did not respond in time
HTTP503 Codeuser_self_deletion_pending DescriptionThe key owner's account on the portal is pending deletion

Full list of common API errors: Errors.

Known specifics

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 before changing the target.

See also