## Первая страница чата `GET /v1/chats/:dialogId/messages/initial` Возвращает страницу сообщений, с которой мессенджер открывает чат. Страница строится вокруг отметки «непрочитано», а если её нет — вокруг последнего прочитанного сообщения. Нужна, чтобы открыть чат там, где пользователь остановился, без отдельного запроса самого чата. Чат вместе с закреплёнными сообщениями отдаёт [загрузка чата](/docs/chats/messages/load). ## Параметры | Параметр | Тип | Обяз. | По умолч. | Описание | |----------|-----|:-----:|-----------|---------| | `dialogId` (path) | string | да | — | ID диалога: числовой ID пользователя для личных сообщений, `chatXXX` для групповых. Алиас `me` — личный диалог текущего пользователя. Диалоги пользователя — в [списке последних диалогов](/docs/chats/discovery/recent) (`GET /v1/chats/recent`) | | `limit` (query) | number | нет | 50 | Сколько сообщений взять по каждую сторону от опорного. От 1 до 200: значение вне диапазона срезается, переданное и применённое значения — в `meta.requestedLimit` и `meta.appliedLimit` | | `ignoreMark` (query) | boolean | нет | `false` | `true` — строить страницу вокруг последнего прочитанного сообщения, не глядя на отметку «непрочитано» | Другие параметры и повторы отклоняются с `400 INVALID_PARAMS`. ## Примеры ### curl — личный ключ ```bash curl "https://vibecode.bitrix24.tech/v1/chats/chat42/messages/initial?limit=20" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### curl — OAuth-приложение ```bash curl "https://vibecode.bitrix24.tech/v1/chats/chat42/messages/initial?limit=20" \ -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/chat42/messages/initial?limit=20', { headers: { 'X-Api-Key': 'YOUR_API_KEY' }, }) const { data } = await res.json() console.log('Сообщения:', data.messages.map((m) => m.id), 'есть старше:', data.hasPrevPage) ``` ### JavaScript — OAuth-приложение ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/chats/chat42/messages/initial?limit=20', { headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', }, }) const { data } = await res.json() console.log('Сообщения:', data.messages.map((m) => m.id), 'есть старше:', data.hasPrevPage) ``` ## Поля ответа | Поле | Тип | Описание | |------|-----|---------| | `success` | boolean | Всегда `true` при успехе | | `data.messages` | array | Сообщения страницы, от старых к новым | | `data.messages[].id` | number | ID сообщения | | `data.messages[].chatId` | number | ID чата | | `data.messages[].authorId` | number | ID автора. `0` — системное сообщение | | `data.messages[].date` | string | Дата отправки (ISO 8601) | | `data.messages[].text` | string | Текст сообщения | | `data.messages[].unread` | boolean | Не прочитано текущим пользователем | | `data.messages[].viewed` | boolean | Просмотрено текущим пользователем | | `data.messages[].viewedByOthers` | boolean | Просмотрено кем-то из участников | | `data.additionalMessages` | array | Сообщения, на которые отвечают сообщения страницы, если самих их на странице нет | | `data.users` | array | Авторы сообщений страницы | | `data.usersShort` | array | Краткие профили пользователей страницы | | `data.files` | array | Файлы сообщений страницы | | `data.reactions` | array | Реакции на сообщения страницы | | `data.stickers` | array | Стикеры сообщений страницы | | `data.forwardSource` | null | Коллекция ленты v2, общая для ответов с сообщениями. Приходит `null`, в том числе когда на странице есть пересланные сообщения | | `data.copilot` | object\|null | Блок CoPilot той же формы, что в [черновом чате CoPilot](/docs/chats/copilot/draft). `null` вне чатов CoPilot | | `data.tariffRestrictions.isHistoryLimitExceeded` | boolean | История старше видимой тарифом скрыта | | `data.hasPrevPage` | boolean | Есть сообщения старше страницы | | `data.hasNextPage` | boolean | Есть сообщения новее страницы | | `meta.requestedLimit` | number | Переданный `limit`, когда он вышел за диапазон от 1 до 200 | | `meta.appliedLimit` | number | Применённое значение `limit` — только если он был приведён к границе | ## Пример ответа ```json { "success": true, "data": { "messages": [ { "id": 1001, "chatId": 42, "authorId": 5, "date": "2026-09-20T10:00:00+03:00", "text": "Посмотрите макет", "params": {} }, { "id": 1002, "chatId": 42, "authorId": 7, "date": "2026-09-20T10:01:00+03:00", "text": "Всё готово", "params": {} } ], "additionalMessages": [], "users": [], "usersShort": [], "files": [], "reactions": [], "stickers": [], "tariffRestrictions": { "isHistoryLimitExceeded": false }, "hasPrevPage": true, "hasNextPage": false } } ``` ## Пример ответа при ошибке 422 — чата нет на портале: ```json { "success": false, "error": { "code": "BITRIX_ERROR", "message": "CHAT_NOT_FOUND", "b24Code": "CHAT_NOT_FOUND" } } ``` ## Ошибки | HTTP | Код | Описание | |------|-----|---------| | 400 | `INVALID_PARAMS` | Параметр кроме `limit` и `ignoreMark`, повтор параметра или некорректное значение. Проверяется до обращения к Битрикс24 | | 404 | `ENTITY_NOT_FOUND` | Битрикс24 вернул код `NOT_FOUND`. Код портала — в `error.b24Code` | | 422 | `BITRIX_ERROR` | Битрикс24 вернул ошибку. Код портала — в `error.b24Code`. Сюда же приходит отсутствующий чат: `CHAT_NOT_FOUND` | | 502 | `ME_ALIAS_RESOLUTION_FAILED` | Не удалось определить пользователя для алиаса `me` | | 403 | `BITRIX_ACCESS_DENIED` | У пользователя нет доступа к чату — Битрикс24 отказал с кодом `ACCESS_DENIED` | | 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `im` | | 403 | `WRITE_BLOCKED_READONLY_KEY` | Загрузка первой страницы выдаёт быстрый доступ к файлам Диска: ключу только для чтения вызов недоступен. Используйте [ленту v2](/docs/chats/messages/list) | | 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов Битрикс24 | Полный список общих ошибок API — [Ошибки](/docs/errors). ## Известные особенности **Начальная страница может менять состояние.** Вызов может сделать вас участником чата, который разрешает автовступление, и выдаёт быстрый доступ к файлам Диска. **Ключи ответа.** Ключи-имена полей приводятся к camelCase: параметр сообщения `FILE_ID` приходит как `fileId`. Ключи-данные остаются как есть: ключи словаря `data.copilot.roles` — коды ролей, и `copilot_assistant` приходит как `copilot_assistant`. **Дальше — лента.** Более старые сообщения читайте [лентой в режиме v2](/docs/chats/messages/list) с `lastId`, равным наименьшему `id` страницы, более новые — с `order=asc` и `lastId`, равным наибольшему. ## Смотрите также - [Загрузка чата](/docs/chats/messages/load) - [Чтение сообщений](/docs/chats/messages/list) - [Сообщения вокруг сообщения](/docs/chats/messages/context)