For AI agents: markdown of this page — /docs-content-en/chats/discovery/access.md documentation index — /llms.txt

Check access to a chat or message

GET /v1/chats/access

Checks whether the current user can open a chat, a message or both.

Parameters

Parameter Type Required Description
ParameterdialogId (query) Typestring Requiredno DescriptionThe chat to check: chatN for a group chat, a numeric user ID for a personal dialog, me — the current user's personal dialog. chatN is the id field of a row in recent dialogs; a user ID comes from the user list
ParametermessageId (query) Typenumber Requiredno DescriptionThe message to check — a positive integer, the id field of a message from the chat history

At least one of the two parameters is required: if neither is passed, there is nothing to check and the request is rejected with 400 MISSING_PARAMS. Other or repeated parameters are rejected with 400 INVALID_PARAMS before any call to Bitrix24.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/chats/access?dialogId=chat42" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/chats/access?dialogId=chat42" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/access?messageId=1002', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})

// No access is an error, not result: false
const canOpen = res.ok && (await res.json()).data.result === true
console.log('Message accessible:', canOpen)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/chats/access?messageId=1002', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const canOpen = res.ok && (await res.json()).data.result === true

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.result Typeboolean DescriptionAlways true: access granted

Response example

JSON 
{
  "success": true,
  "data": {
    "result": true
  }
}

Error response example

422 — the message does not exist in the Bitrix24 account:

JSON 
{
  "success": false,
  "error": {
    "code": "BITRIX_ERROR",
    "message": "MESSAGE_NOT_FOUND",
    "b24Code": "MESSAGE_NOT_FOUND"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_PARAMS DescriptionNeither dialogId nor messageId was passed
HTTP400 CodeINVALID_PARAMS DescriptionmessageId is not a positive integer, dialogId is empty, a parameter other than dialogId and messageId is passed, or a parameter is repeated
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionNo access to the chat or the message
HTTP404 CodeENTITY_NOT_FOUND DescriptionBitrix24 returned "not found". The portal code is in error.b24Code
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error. The portal code is in error.b24Code. CHAT_NOT_FOUND — the chat does not exist on the portal, MESSAGE_NOT_FOUND — the message does not exist
HTTP502 CodeME_ALIAS_RESOLUTION_FAILED DescriptionFailed to resolve the user when using the me alias
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the im scope
HTTP403 CodeWRITE_BLOCKED_READONLY_KEY DescriptionThe key is in read-only mode, and either the request was not made with an employee's personal key or the dialogId passed does not point to an existing dialog
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured

The full list of common API errors — Errors.

Known specifics

The checks are independent. With both parameters the endpoint checks the chat and the message separately and does not verify that the message belongs to that chat. To find the chat of a message, open the chat around the message.

The check may make you a member. The check follows the same path as opening the chat: when the chat allows auto-join — a comment chat, a collab or a task chat, for example — the call adds the current user as a member. This targeted read operation is available to a READONLY key when it is an employee's personal key with the im scope. A dialogId, if passed, must point to an existing dialog: chatN or a user ID from that employee's recent dialogs. It does not mark messages as read by itself.

See also