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

Intercept a dialog

POST /v1/openlines/sessions/intercept

Transfers an Open Channel dialog to the current operator: the previous operator is no longer the lead on this session. Works on any Bitrix24 account and does not wait for the imopenlines 26.700.0 update.

Important: the call changes a live dialog with the client — after it, the operator becomes a participant in the conversation. Permissions are checked by Bitrix24, and a Bitrix24 account administrator passes this check for any dialog in the account.

Request fields (body)

Field Type Required Description
FieldchatId Typenumber | string Requiredyes DescriptionOpen Channel chat identifier: a number (4531) or a string of the form chat4531. CHAT_ID is accepted instead of chatId, but dialogId is not. Sources: GET /v1/openlines/crm/chats by CRM card, the sessions[].chatId field in the POST /v1/openlines/sessions/search response

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/openlines/sessions/intercept \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": 4531 }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/openlines/sessions/intercept \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "chatId": 4531 }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/openlines/sessions/intercept', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ chatId: 4531 }),
})

const { success, data, error } = await res.json()
if (!success) throw new Error(`${error.code}: ${error.message}`)
console.log('Intercepted:', data.intercepted)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/openlines/sessions/intercept', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ chatId: 4531 }),
})

const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on a successful interception
Fielddata.chatId Typenumber DescriptionChat identifier from the request. The chat4531 form is returned as a number
Fielddata.intercepted Typeboolean DescriptionAlways true

Response example

JSON 
{
  "success": true,
  "data": {
    "chatId": 4531,
    "intercepted": true
  }
}

Error response example

400 — chatId does not parse into a chat identifier:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "chatId must be a positive whole number within the safe integer range — either 2043 or the \"chat2043\" form. Take it from `data.chat.id` of the bot event (its `data.dialogId` twin is the same id prefixed with `chat`), or from `sessions[].chatId` of POST /v1/openlines/sessions/search."
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_PARAMS DescriptionchatId was not passed
HTTP400 CodeINVALID_PARAMS DescriptionchatId does not parse into a chat identifier: a positive integer and the chat<N> form are accepted. The same code when the request body is not a JSON object
HTTP400 CodeINVALID_JSON_BODY DescriptionThe request body does not parse as JSON
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
HTTP401 CodeINVALID_API_KEY DescriptionThe key was not recognized
HTTP401 CodeTOKEN_MISSING DescriptionThe personal key has no access to the Bitrix24 account, or the application key was sent without a session token in Authorization
HTTP403 CodeSCOPE_DENIED DescriptionThe key has no imopenlines scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only, while sessions/intercept changes the dialog
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe key's user has no access to the dialog
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 refused, and its code comes in error.b24Code. A chat with this identifier does not exist or the chat is not an Open Channel — both cases give OPERATOR_WRONG. The error.message text comes from Bitrix24 verbatim, in English
HTTP429 CodeRATE_LIMITED DescriptionTwo sources return this code. The first is the platform's own operation limit: a platform ceiling of 120 requests per minute per Bitrix24 account rather than per key, split across replicas. Take the effective value from the x-ratelimit-limit header, the remaining quota and the reset time from x-ratelimit-remaining and x-ratelimit-reset. These headers come with every response. The second is Bitrix24 rejecting the call under its request rate limit: the response carries a Retry-After header
HTTP502 CodeOPENLINE_SESSION_FAILED DescriptionBitrix24 responded without confirmation — result is not true, yet it returned no error
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a response of an unexpected shape
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 accepted the call but did not respond within the allotted time. The call may still have been executed

Full list of common API errors: Errors.

Known specifics

  • Dialog completion is not checked. Interception succeeds even on a dialog whose session closed long ago: the operator is added to the chat participants, and the response is intercepted: true. To work only with open dialogs, take chatId from GET /v1/openlines/crm/chats without activeOnly=false.

See also