Поиск чатов

Найдите нужный чат: список последних диалогов, счётчики непрочитанного, чат конкретной CRM-сущности, поиск по тексту и информация об отдельном диалоге.

Скоуп: im | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key

Последние диалоги

GET /v1/chats/recent

Возвращает список последних диалогов текущего пользователя: закреплённые диалоги первыми, далее по времени последнего сообщения. Каждый элемент содержит краткую информацию о диалоге, последнем сообщении и счётчике непрочитанных.

Параметры

Режим дельты. Параметр updatedAfter переключает эндпоинт в режим «что изменилось с указанного момента»: GET /v1/chats/recent?updatedAfter=2026-06-28T00:00:00Z. В ответ приходит массив диалогов, у которых dateUpdate не раньше переданного момента. Граница включительна — диалог с dateUpdate, равным переданному моменту, попадает в ответ, поэтому при сдвиге курсора на максимальное увиденное значение пограничная запись придёт повторно.

Размером выборки в этом режиме управляет сервер: читается одна страница до 200 диалогов. Переданный limit на неё не влияет и возвращается в meta.requestedLimit вместе с применённым meta.appliedLimit.

Если в meta пришло truncated со значением true, дельта может быть неполной: Битрикс24 сообщил, что за отданной страницей есть ещё диалоги, либо форму ответа не удалось разобрать. В этом случае не сдвигайте updatedAfter, а получите полный список постраничным режимом с курсором lastMessageDate. Число возвращённых строк признаком полноты не является — короткий ответ приходит и тогда, когда за ним есть ещё данные.

Дата без явного смещения — например 2026-06-29 10:00:00 — отклоняется с 400 INVALID_PARAMS: такое значение читается по-разному в зависимости от часового пояса сервера, поэтому момент требуется указать однозначно.

Режим v2. format=v2 переключает эндпоинт на методы мессенджера v2: первая страница — im.v2.Recent.load (без lastMessageDate), следующие — im.v2.Recent.tail (с ним). В data приходит объект v2 — recentItems и коллекции chats, users, messages, files — с ключами в camelCase. Режим принимает только format, limit, lastMessageDate и unreadOnly (true или false); любой другой параметр, в том числе параметры прежнего режима и их формы в верхнем регистре (OFFSET, LIMIT, LAST_UPDATE), отклоняется с 400 INVALID_PARAMS и именем параметра. Список всегда общий, без вложенных разделов. У режима своя корзина лимита запросов, отдельная от прежнего режима.

Курсор следующей страницы — наименьшая непустая dateLastActivity среди незакреплённых строк текущей страницы; сравнивайте моменты времени, а не строки: смещение у дат бывает разным. Граница включительная, а закреплённые чаты с датой не новее курсора открывают каждую страницу — повторы снимайте по chatId. Конец списка — только hasNextPage: false. Если при hasNextPage: true курсора нет или он равен прежнему, повторите запрос с бо́льшим limit, вплоть до 200; true без продвижения и при 200 — отказ, а не конец списка. Строк ответа не отбрасывайте, даже когда показываете меньше: курсор считается по всему ответу, и отброшенные строки больше не придут. Обход — не снимок: чат, поднятый новой активностью из-под курсора во время обхода, в нём не появится, поэтому после обхода перечитайте первую страницу. Для полного обхода берите limit=200: закреплённые строки повторяются на каждой странице, и маленькая страница тратит запросы на повторы.

Примеры

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

curl "https://vibecode.bitrix24.tech/v1/chats/recent?limit=20" \
  -H "X-Api-Key: YOUR_API_KEY"

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

curl "https://vibecode.bitrix24.tech/v1/chats/recent?limit=20" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/recent?limit=20', {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Последние диалоги:', data.items)

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

const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/recent?limit=20', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()

Поля ответа

В режиме дельты data — массив диалогов с теми же полями элемента, что перечислены выше для data.items. Поля hasMorePages и hasMore в этом режиме не возвращаются, их роль выполняет meta.truncated.

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

Постраничный режим:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "chat456",
        "chatId": 456,
        "type": "chat",
        "title": "Команда разработки",
        "avatar": {
          "url": "",
          "color": "#4ba984"
        },
        "message": {
          "id": 1201,
          "text": "Обновление задачи готово",
          "authorId": 1,
          "date": "2026-06-03T16:51:12+03:00",
          "file": false,
          "attach": false,
          "sticker": null,
          "status": "received"
        },
        "lastId": 1195,
        "pinned": false,
        "unread": false,
        "counter": 0,
        "dateUpdate": "2026-06-03T16:51:12+03:00",
        "dateLastActivity": "2026-06-03T16:51:12+03:00",
        "chat": {
          "id": 456,
          "name": "Команда разработки",
          "type": "chat",
          "owner": 1,
          "userCounter": 5,
          "role": "OWNER",
          "entityType": "",
          "entityId": ""
        }
      },
      {
        "id": "chat123",
        "chatId": 123,
        "type": "crm",
        "title": "Чат по сделке",
        "avatar": {
          "url": "",
          "color": "#f76187"
        },
        "message": {
          "id": 980,
          "text": "Договор согласован",
          "authorId": 7,
          "date": "2026-06-02T14:08:10+03:00",
          "file": false,
          "attach": false,
          "sticker": null,
          "status": "received"
        },
        "lastId": 0,
        "pinned": false,
        "unread": false,
        "counter": 0,
        "dateUpdate": "2026-06-02T14:08:10+03:00",
        "dateLastActivity": "2026-06-02T14:08:10+03:00",
        "chat": {
          "id": 123,
          "name": "Чат по сделке",
          "type": "crm",
          "owner": 1,
          "userCounter": 2,
          "role": "MEMBER",
          "entityType": "CRM",
          "entityId": "DEAL|42"
        }
      }
    ],
    "hasMorePages": true,
    "hasMore": true
  }
}

Режим дельты. Показаны основные поля элемента, полный набор — в таблице выше:

{
  "success": true,
  "data": [
    {
      "id": "chat456",
      "chatId": 456,
      "type": "chat",
      "title": "Команда разработки",
      "pinned": false,
      "unread": false,
      "counter": 0,
      "dateUpdate": "2026-06-29T10:12:44+03:00",
      "dateLastActivity": "2026-06-29T10:12:44+03:00"
    }
  ],
  "meta": {
    "mode": "delta",
    "returned": 1
  }
}

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

403 — нет скоупа im:

{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'im' scope"
  }
}

Ошибки

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

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

• Флаги skipOpenLines и onlyOpenLines взаимоисключающие: включение обоих приводит к результату, при котором ни один из чатов открытых линий не попадёт в список.
• Порядок между страницами по offset гарантирован, пока окно вместе с запасом на недогидрированные строки помещается в одну страницу Битрикс24: за вызов Битрикс24 отдаёт не больше 200 записей, запас на недогидрированные строки — 10, поэтому граница проходит там, где смещение плюс размер страницы не превышает 190. Внутри этой границы Вайбкод нарезает окна на своей стороне, поэтому соседние страницы не пересекаются и диалогов не теряют. За этой границей смещение уходит в Битрикс24, где список пересобирается при каждом новом сообщении, и соседние страницы снова могут пересечься или пропустить диалог. Курсор lastMessageDate обходит это ограничение, но граница у него включительная: Битрикс24 отдаёт диалоги с dateLastActivity не позже переданного значения, и закреплённые чаты идут первыми на каждой странице. Передайте dateLastActivity последнего незакреплённого элемента текущей страницы и не передавайте offset: вместе с курсором смещение отсчитывается от начала уже отфильтрованного списка, и сдвиг offset на размер страницы пропускает столько же диалогов. Повторы на границе — диалоги с той же датой и закреплённые чаты — отбрасывайте по chatId. Если курсор не продвинулся, потому что всю страницу заняли диалоги с одной и той же датой, повторите запрос с большим limit, до 200.
• Ответ содержит поле data.copilot с конфигурацией AI-ассистента портала. Структура используется для отображения ролей в интерфейсе Битрикс24 и не является частью списка диалогов.
• В режиме дельты диалог с нечитаемым значением dateUpdate остаётся в ответе: лишняя запись безопаснее потерянного изменения.
• Фильтры семейств skip*, only* и unreadOnly действуют и в режиме дельты, сужая просматриваемую страницу.
• В режиме v2 ключи-имена полей приводятся к camelCase, а ключи-данные остаются как есть: словарь data.copilot.roles ключуется кодом роли, и copilot_assistant приходит как copilot_assistant — тем же значением, что role у чата, поэтому роль находится прямым обращением roles[role].
• На портале без методов v2 режим отвечает 422 BITRIX_ERROR с кодом портала в error.b24Code и не откатывается на прежний ответ молча: форма ответа другая.

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

• Поиск чатов
• Найти чат CRM-сущности
• Информация о диалоге
• Поиск чатов