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

Shared chats with a user

GET /v1/chats/shared

Returns the chats in which both the current user and the given employee are members. Use it for a "Shared chats" block in the other person's profile card.

Parameters

Parameter Type Required Default Description
userId (query) integer yes — Employee ID, 1 or more. List — GET /v1/users
limit (query) integer no 50 Chats per page, 1 to 200. A smaller value is raised to 1 and a larger one is clamped to 200, both echoed in meta
offset (query) integer no 0 How many chats to skip, 0 or more

Other parameters and repeated parameters are rejected with 400 INVALID_PARAMS.

Walk. Request the next page with offset increased by the applied limit. The list ends at an empty page, data.chats with no items. A short page is not the end: a page can be shorter than limit while more chats follow.

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/chats/shared?userId=4&limit=50" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/chats/shared?userId=4&limit=50" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const shared = []
for (let offset = 0; ; offset += 50) {
  const url = `https://vibecode.bitrix24.com/v1/chats/shared?userId=4&limit=50&offset=${offset}`
  const res = await fetch(url, { headers: { 'X-Api-Key': 'YOUR_API_KEY' } })
  const { data } = await res.json()
  if (data.chats.length === 0) break
  shared.push(...data.chats)
}

JavaScript — OAuth application

javascript 
const shared = []
for (let offset = 0; ; offset += 50) {
  const url = `https://vibecode.bitrix24.com/v1/chats/shared?userId=4&limit=50&offset=${offset}`
  const res = await fetch(url, {
    headers: {
      'X-Api-Key': 'YOUR_APP_KEY',
      'Authorization': 'Bearer USER_SESSION_TOKEN',
    },
  })
  const { data } = await res.json()
  if (data.chats.length === 0) break
  shared.push(...data.chats)
}

Response fields

Field Type Description
success boolean Always true on success
data.chats array Shared chats. An empty array is the end of the list
data.chats[].id number Chat ID
data.chats[].dialogId string Dialog ID, chatXXX, for the message endpoints
data.chats[].name string Chat name
data.chats[].type string Chat type: chat, general, openChannel, collab, calendar and others
data.chats[].owner number ID of the chat owner
data.chats[].role string The current user's role: owner, manager, member
data.chats[].dateMessage string Instant of the chat's last message
meta.requestedLimit number The limit passed. It arrives together with appliedLimit, only when the value was outside the range of 1 to 200
meta.appliedLimit number The limit applied

Response example

The main fields are shown:

JSON 
{
  "success": true,
  "data": {
    "chats": [
      {
        "id": 1,
        "dialogId": "chat1",
        "name": "General chat",
        "type": "general",
        "owner": 0,
        "role": "member",
        "dateMessage": "2026-09-24T18:02:11+00:00"
      },
      {
        "id": 264431,
        "dialogId": "chat264431",
        "name": "Release preparation",
        "type": "chat",
        "owner": 1,
        "role": "owner",
        "dateMessage": "2026-09-24T21:10:22+00:00"
      }
    ]
  }
}

Error response example

400 — no userId:

JSON 
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "`userId` is required: the user whose shared chats to list."
  }
}

Errors

HTTP Code Description
400 INVALID_PARAMS No userId, userId less than 1, offset less than 0, a non-numeric limit, a parameter other than userId, limit, offset, or a repeated parameter. Checked before the Bitrix24 call
422 BITRIX_ERROR Bitrix24 returned an error; the Bitrix24 code is in error.b24Code
403 BITRIX_ACCESS_DENIED Bitrix24 denied access
403 SCOPE_DENIED The API key does not have the im scope
401 TOKEN_MISSING The API key has no Bitrix24 tokens configured
502 BITRIX_UNAVAILABLE Bitrix24 is unavailable or returned a server error

Full list of common API errors — Errors.

Known specifics

The response has no next-page flag. The walk runs until an empty page, so the last request of a walk always returns an empty data.chats.

See also