Поиск чатов по тексту

GET /v1/chats/search

Ищет чаты и диалоги по названию или тексту сообщений. Возвращает массив объектов чатов, соответствующих поисковому запросу.

Параметры

Параметр Тип Обяз. Описание
search string да Поисковая строка. При пустом значении возвращает результаты без фильтрации

Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/chats/search?search=%D0%A1%D0%B4%D0%B5%D0%BB%D0%BA%D0%B0" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/chats/search?search=%D0%A1%D0%B4%D0%B5%D0%BB%D0%BA%D0%B0" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

javascript 
const query = new URLSearchParams({ search: 'Сделка' })
const res = await fetch(`https://vibecode.bitrix24.tech/v1/chats/search?${query}`, {
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const { data } = await res.json()
console.log('Найдено чатов:', data.length)

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

javascript 
const query = new URLSearchParams({ search: 'Сделка' })
const res = await fetch(`https://vibecode.bitrix24.tech/v1/chats/search?${query}`, {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()

Поля ответа

Поле Тип Описание
data array Массив найденных чатов
data[].id number Числовой ID чата
data[].name string Название чата
data[].description string Описание чата
data[].type string Тип чата: chat, general, openlines, copilot, channel, crm, tasks и другие
data[].owner number ID владельца чата
data[].userCounter number Количество участников
data[].messageCount number Общее количество сообщений
data[].counter number Количество непрочитанных сообщений
data[].unreadId number ID первого непрочитанного сообщения
data[].lastMessageId number ID последнего сообщения
data[].entityType string Тип связанной сущности (CRM, TASKS, GENERAL и другие)
data[].entityId string ID связанной сущности
data[].entityLink object Ссылка на связанную сущность
data[].entityLink.type string Тип ссылки
data[].entityLink.url string Относительный URL сущности на портале
data[].entityLink.id string ID сущности в строковом формате
data[].dateCreate string Дата создания чата (ISO 8601)
data[].role string Роль текущего пользователя: owner, manager, member
data[].extranet boolean Является ли чат экстранет-чатом
data[].permissions object Права участников по операциям

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

JSON 
{
  "success": true,
  "data": [
    {
      "id": 456,
      "name": "Чат по сделке",
      "description": "Здесь обсуждаем детали сделки",
      "type": "crm",
      "owner": 1,
      "userCounter": 3,
      "messageCount": 9,
      "counter": 0,
      "unreadId": 0,
      "lastMessageId": 1450,
      "entityType": "CRM",
      "entityId": "DEAL|42",
      "entityLink": {
        "type": "CRM",
        "url": "/crm/deal/details/42/",
        "id": "DEAL|42"
      },
      "dateCreate": "2026-03-03T15:07:38+03:00",
      "role": "owner",
      "extranet": false,
      "permissions": {
        "manageUsersAdd": "member",
        "manageUsersDelete": "manager",
        "manageUi": "member",
        "manageSettings": "owner",
        "manageMessages": "member",
        "canPost": "member"
      }
    },
    {
      "id": 789,
      "name": "Обсуждение сделки №5",
      "description": null,
      "type": "chat",
      "owner": 12,
      "userCounter": 2,
      "messageCount": 4,
      "counter": 0,
      "unreadId": 0,
      "lastMessageId": 890,
      "entityType": "",
      "entityId": "",
      "entityLink": {
        "type": "",
        "url": "",
        "id": ""
      },
      "dateCreate": "2026-02-26T15:56:08+03:00",
      "role": "member",
      "extranet": false,
      "permissions": {
        "manageUsersAdd": "member",
        "manageUsersDelete": "manager",
        "manageUi": "member",
        "manageSettings": "owner",
        "manageMessages": "member",
        "canPost": "member"
      }
    }
  ]
}

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

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

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

Ошибки

HTTP Код Описание
403 SCOPE_DENIED API-ключ не имеет скоупа im
401 TOKEN_MISSING API-ключ не имеет настроенных токенов Битрикс24
422 BITRIX_ERROR Битрикс24 вернул ошибку (подробности в message)
502 BITRIX_UNAVAILABLE Битрикс24 недоступен или вернул ошибку сервера

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

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

  • Поиск выполняется по названию чата. Соответствие сообщениям зависит от возможностей портала и не гарантировано для всех типов чатов.
  • Результаты не поддерживают пагинацию через limit и offset. При необходимости получить большее число результатов уточняйте поисковый запрос.
  • Для поиска чата конкретной CRM-сущности используйте GET /v1/chats/find — он принимает entityType и entityId и возвращает точное совпадение.

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