Для AI-агентов: markdown этой страницы — /docs-content/chats/discovery/shared.md индекс документации — /llms.txt

Общие чаты с пользователем

GET /v1/chats/shared

Возвращает чаты, в которых текущий пользователь состоит вместе с указанным сотрудником. Подходит для блока «Общие чаты» в карточке собеседника.

Параметры

Параметр Тип Обяз. По умолч. Описание
userId (query) integer да — ID сотрудника, не меньше 1. Список: GET /v1/users
limit (query) integer нет 50 Чатов на странице, от 1 до 200. Меньшее значение поднимается до 1, большее срезается до 200, оба раза с эхом в meta
offset (query) integer нет 0 Сколько чатов пропустить, не меньше 0

Другие параметры и повторы отклоняются с 400 INVALID_PARAMS.

Обход. Следующую страницу запрашивайте с offset, увеличенным на применённый limit. Конец списка — пустая страница, data.chats без элементов. Короткая страница концом не считается: страница бывает короче limit, хотя дальше есть ещё чаты.

Примеры

curl — личный ключ

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

curl — OAuth-приложение

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

JavaScript — личный ключ

javascript 
const shared = []
for (let offset = 0; ; offset += 50) {
  const url = `https://vibecode.bitrix24.tech/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-приложение

javascript 
const shared = []
for (let offset = 0; ; offset += 50) {
  const url = `https://vibecode.bitrix24.tech/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)
}

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.chats array Общие чаты. Пустой массив — конец списка
data.chats[].id number ID чата
data.chats[].dialogId string ID диалога, chatXXX — для эндпоинтов сообщений
data.chats[].name string Название чата
data.chats[].type string Тип чата: chat, general, openChannel, collab, calendar и другие
data.chats[].owner number ID владельца чата
data.chats[].role string Роль текущего пользователя: owner, manager, member
data.chats[].dateMessage string Момент последнего сообщения чата
meta.requestedLimit number Переданный limit. Приходит вместе с appliedLimit, только когда значение вышло за диапазон от 1 до 200
meta.appliedLimit number Применённый limit — только если он был приведён к границе

Пример ответа

Показаны основные поля:

JSON 
{
  "success": true,
  "data": {
    "chats": [
      {
        "id": 1,
        "dialogId": "chat1",
        "name": "Общий чат",
        "type": "general",
        "owner": 0,
        "role": "member",
        "dateMessage": "2026-09-24T18:02:11+00:00"
      },
      {
        "id": 264431,
        "dialogId": "chat264431",
        "name": "Подготовка релиза",
        "type": "chat",
        "owner": 1,
        "role": "owner",
        "dateMessage": "2026-09-24T21:10:22+00:00"
      }
    ]
  }
}

Пример ответа при ошибке

400 — нет userId:

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

Ошибки

HTTP Код Описание
400 INVALID_PARAMS Нет userId, userId меньше 1, offset меньше 0, нечисловой limit, параметр вне userId, limit, offset или повтор параметра. Проверяется до обращения к Битрикс24
422 BITRIX_ERROR Битрикс24 вернул ошибку, код портала — в error.b24Code
403 BITRIX_ACCESS_DENIED Битрикс24 отказал в доступе
403 SCOPE_DENIED API-ключ не имеет скоупа im
401 TOKEN_MISSING API-ключ не имеет настроенных токенов Битрикс24
502 BITRIX_UNAVAILABLE Битрикс24 недоступен или вернул ошибку сервера

Полный список общих ошибок API — Ошибки.

Известные особенности

В ответе нет признака следующей страницы. Обход идёт до пустой страницы, поэтому последний запрос обхода всегда возвращает пустой data.chats.

Смотрите также