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
ParameteruserId (query) Typeinteger Requiredyes Default— DescriptionEmployee ID, 1 or more. List: GET /v1/users
Parameterlimit (query) Typeinteger Requiredno Default50 DescriptionChats per page, 1 to 200. A smaller value is raised to 1 and a larger one is clamped to 200, both echoed in meta
Parameteroffset (query) Typeinteger Requiredno Default0 DescriptionHow many chats to skip, 0 or more

Other parameters and repeated parameters are rejected with 400 INVALID_PARAMS.

Pagination. 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
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.chats Typearray DescriptionShared chats. An empty array is the end of the list
Fielddata.chats[].id Typenumber DescriptionChat ID
Fielddata.chats[].dialogId Typestring DescriptionDialog ID, chatXXX, for the message endpoints
Fielddata.chats[].name Typestring DescriptionChat name
Fielddata.chats[].type Typestring DescriptionChat type: chat, general, openChannel, collab, calendar and others
Fielddata.chats[].owner Typenumber DescriptionID of the chat owner
Fielddata.chats[].role Typestring DescriptionThe current user's role: owner, manager, member
Fielddata.chats[].dateMessage Typestring DescriptionTime of the chat's last message
Fieldmeta.requestedLimit Typenumber DescriptionThe limit passed. It arrives together with appliedLimit, only when the value was outside the range of 1 to 200
Fieldmeta.appliedLimit Typenumber DescriptionThe limit applied — only when it was clamped to a bound

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
HTTP400 CodeINVALID_PARAMS DescriptionNo 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
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 returned an error; the Bitrix24 code is in error.b24Code
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied access
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the im scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no Bitrix24 tokens configured
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a server error

Full list of common API errors — Errors.

Known specifics

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

See also