Поиск чатов

Найдите нужный чат: список последних диалогов, чат конкретной 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: такое значение читается по-разному в зависимости от часового пояса сервера, поэтому момент требуется указать однозначно.

Примеры

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 на живом портале не гарантирован: список пересобирается при каждом новом сообщении, соседние страницы могут пересечься или пропустить диалог. Для устойчивого обхода используйте курсор lastMessageDate: передайте значение dateLastActivity последнего элемента текущей страницы, чтобы получить следующую порцию. При этом передавайте и offset, чтобы избежать дублирования записей на границе страниц.
• Ответ содержит поле data.copilot с конфигурацией AI-ассистента портала. Структура используется для отображения ролей в интерфейсе Битрикс24 и не является частью списка диалогов.
• В режиме дельты диалог с нечитаемым значением dateUpdate остаётся в ответе: лишняя запись безопаснее потерянного изменения.
• Фильтры семейств skip*, only* и unreadOnly действуют и в режиме дельты, сужая просматриваемую страницу.

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

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