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 — the v2 messenger method im.v2.Access.check. If the user has access, the response is data.result: true. If not, the response is an error rather than false: 403 BITRIX_ACCESS_DENIED, or 422 BITRIX_ERROR when the chat or the message does not exist in the Bitrix24 account.

Parameters

Parameter Type Required Description
dialogId (query) string no The chat to check: chatN for a group chat, a numeric user ID for a personal dialog, me — the current user's personal dialog
messageId (query) number no The message to check — a positive integer

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
success boolean Always true on success
data.result boolean Always 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
400 MISSING_PARAMS Neither dialogId nor messageId was passed
400 INVALID_PARAMS messageId is not a positive integer, dialogId is empty, or the request has a parameter other than dialogId and messageId or a repeated parameter
403 BITRIX_ACCESS_DENIED No access to the chat or the message
404 ENTITY_NOT_FOUND Bitrix24 returned "not found"; the portal code is in error.b24Code
422 BITRIX_ERROR Bitrix24 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
502 ME_ALIAS_RESOLUTION_FAILED Failed to resolve the user when using the me alias
403 SCOPE_DENIED The API key does not have the im scope
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured

The full list of common API errors — Errors.

Known specifics

The checks are independent. With both parameters Bitrix24 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 exact read operation is allowed for a READONLY key, subject to the im scope and the user's Bitrix24 access. It does not mark messages read.

See also