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

Open a client chat

POST /v1/openlines/sessions/open

Finds an Open Channel chat by the client's code in the connector. The identifier of the found chat is needed to pick up the dialog and perform operator actions.

Request fields (body)

Field Type Required Description
FielduserCode Typestring Requiredyes DescriptionThe client's code in the connector, in the form connector|lineId|externalChatId|userId. Passed unchanged. Source: the userCode field in the POST /v1/openlines/sessions/search response

Examples

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/openlines/sessions/open \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userCode": "doccheck|59|cloud-chat-2|1575"}'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/openlines/sessions/open \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userCode": "doccheck|59|cloud-chat-2|1575"}'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/openlines/sessions/open', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userCode: 'doccheck|59|cloud-chat-2|1575' }),
})

const { data } = await res.json()
console.log('Chat ID:', data.chatId)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/openlines/sessions/open', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ userCode: 'doccheck|59|cloud-chat-2|1575' }),
})

const { data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue on a successful response
Fielddata.chatId Typenumber DescriptionOpen Channel chat identifier. See Chat ID

Response example

JSON 
{
  "success": true,
  "data": {
    "chatId": 5255
  }
}

Error response example

400 — the client's code is missing:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "userCode is required and must be a non-empty string"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_REQUIRED_FIELDS DescriptionThe userCode field is missing, is not a string, is empty or consists of whitespace
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 rejected the request. The refusal text is in message
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe employee the call runs as has no permission for the action, or there is no client with this userCode. Both causes return the same response
HTTP502 CodeOPENLINE_OPERATOR_FAILED DescriptionBitrix24 did not return a chat identifier
HTTP403 CodeSCOPE_DENIED DescriptionThe key has no imopenlines scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is read-only. Finding a chat by the client's code requires a key with write access
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header is missing
HTTP401 CodeINVALID_API_KEY DescriptionThe key is not recognized
HTTP401 CodeTOKEN_MISSING DescriptionA personal key has no access to the Bitrix24 portal, or an application key was sent without a session token in Authorization
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or the connection to it broke before the response was complete

Full list of common API errors — Errors.

Known specifics

  • The call does not start a session. For a dialog with a closed session, the method returns chatId, and the session stays closed. To pick up the dialog, use POST /v1/openlines/sessions/start.

See also