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

Получить избранные сообщения

GET /v1/chats/:dialogId/favorites

Возвращает постранично строки избранного текущего пользователя в одном чате вместе с сообщениями и их авторами.

Параметры

Параметр Тип Обяз. Описание
ПараметрdialogId (path) Типstring Обяз.да Описаниеchat и реальный ID чата из загрузки чата, в том числе личного. Числовой ID собеседника и me отклоняются
Параметрlimit (query) Типinteger Обяз.нет ОписаниеСтрок на страницу: 1–50, по умолчанию 50. Выход за границы ограничивается с отражением в meta.requestedLimit и meta.appliedLimit
ПараметрlastId (query) Типinteger Обяз.нет ОписаниеИсключающий курсор: id последней строки предыдущей страницы
Параметрsearch (query) Типstring Обяз.нет ОписаниеПоиск по тексту сообщения

Нужен скоуп im. Текущий пользователь определяется по токенам авторизации. Параметры выбора владельца и неизвестные параметры отклоняются.

Примеры

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

Terminal
curl -X GET "https://vibecode.bitrix24.tech/v1/chats/chat1945/favorites" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal
curl -X GET "https://vibecode.bitrix24.tech/v1/chats/chat1945/favorites" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/chat1945/favorites', {
  method: 'GET',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})
const { data } = await res.json()
console.log(data)

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

javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/chat1945/favorites', {
  method: 'GET',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data } = await res.json()
console.log(data)

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean Описаниеtrue
Полеdata.list Типarray ОписаниеСтроки избранного
Полеdata.list[].id Типnumber ОписаниеID связи избранного и курсор следующей страницы
Полеdata.list[].messageId Типnumber ОписаниеID сообщения
Полеdata.list[].chatId Типnumber ОписаниеРеальный ID чата
Полеdata.list[].authorId Типnumber ОписаниеID владельца избранного
Полеdata.list[].dateCreate Типstring ОписаниеДата добавления в избранное
Полеdata.list[].message Типobject ОписаниеСообщение: id, chatId, authorId, date, text, isSystem, params и признаки прочтения
Полеdata.messages, data.additionalMessages Типarray ОписаниеСопутствующие сообщения. Приходят не в каждом ответе
Полеdata.users, data.files Типarray ОписаниеСвязанные пользователи и файлы
Полеdata.usersShort, data.reactions, data.stickers Типarray ОписаниеКраткие сведения о пользователях, реакции и стикеры сообщений из data.list. Приходят не в каждом ответе: в пустой выдаче их нет
Полеdata.tariffRestrictions.isHistoryLimitExceeded Типboolean Описаниеtrue, когда тариф скрывает часть старой истории чата и её сообщения не попадают в выдачу
Полеmeta.requestedLimit Типnumber ОписаниеПереданный limit. Приходит вместе с appliedLimit, только когда значение вышло за диапазон от 1 до 50
Полеmeta.appliedLimit Типnumber ОписаниеПрименённое значение limit — только если оно было приведено к границе

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

Показаны основные поля сообщения и пользователя.

JSON
{
  "success": true,
  "data": {
    "list": [
      {
        "id": 15,
        "messageId": 846,
        "chatId": 1945,
        "authorId": 7,
        "dateCreate": "2026-11-17T10:05:00+03:00",
        "message": {
          "id": 846,
          "chatId": 1945,
          "authorId": 12,
          "date": "2026-11-16T09:30:00+03:00",
          "text": "Release notes are ready",
          "isSystem": false,
          "params": {"favorite": ["7"]},
          "unread": false,
          "viewed": true
        }
      },
      {
        "id": 14,
        "messageId": 845,
        "chatId": 1945,
        "authorId": 7,
        "dateCreate": "2026-11-17T10:04:00+03:00",
        "message": {
          "id": 845,
          "chatId": 1945,
          "authorId": 12,
          "date": "2026-11-16T09:28:00+03:00",
          "text": "Project update",
          "isSystem": false,
          "params": {"favorite": ["7"]},
          "unread": false,
          "viewed": true
        }
      }
    ],
    "users": [{"id": 12, "active": true, "name": "Anna Smith", "type": "user"}],
    "usersShort": [],
    "files": [],
    "reactions": [],
    "stickers": [],
    "tariffRestrictions": {"isHistoryLimitExceeded": false}
  }
}

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

400 — передан неизвестный параметр:

JSON
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Query parameter `ownerId` is not accepted by GET /v1/chats/:dialogId/favorites. Accepted: lastId, limit, search."
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодINVALID_PARAMS ОписаниеНекорректный ID, неизвестный или повторный параметр либо поле тела
HTTP422 КодBITRIX_ERROR Описаниеerror.b24Code равен ACCESS_ERROR — у сотрудника нет доступа к чату или чата нет
HTTP401 КодMISSING_API_KEY ОписаниеНе передан API-ключ
HTTP401 КодTOKEN_MISSING ОписаниеНет настроенных токенов Битрикс24
HTTP403 КодSCOPE_DENIED ОписаниеУ ключа нет скоупа im
HTTP403 КодBITRIX_ACCESS_DENIED ОписаниеУ текущего пользователя нет доступа
HTTP404 КодENTITY_NOT_FOUND ОписаниеЗапись не найдена
HTTP422 КодBITRIX_ERROR ОписаниеБитрикс24 отклонил операцию с другим кодом, он — в error.b24Code

Общие ошибки API — Ошибки.

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

Строки идут по убыванию ID связи избранного. Завершите чтение, когда строк меньше фактического размера страницы. По умолчанию это 50, для допустимого limit — переданное значение, при ограничении — meta.appliedLimit. Список не следует загружать при каждом открытии меню сообщения.

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