# Чат задачи

`GET /v1/tasks/:taskId/chat/messages`

Читает ленту чата задачи — новые сообщения первыми. У каждой задачи в Битрикс24 есть групповой чат, и эндпоинт сам определяет чат по ID задачи — знать ID чата не нужно. Типичный сценарий — выгрузка финальных сообщений по закрытой задаче.

Битрикс24 API: `im.v2.Chat.Message.tail` (на старых порталах — `im.dialog.messages.get`)
Скоуп: `task`, `im`

## Параметры запроса (query)

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|---------|
| `limit` | number | | Сообщений на страницу, 1..200, по умолчанию 50 |
| `lastId` | number | | Курсор: вернуть сообщения старше этого `id`. Для следующей страницы передайте минимальный `id` из текущей |

## Пример

```bash
curl "https://vibecode.bitrix24.tech/v1/tasks/53/chat/messages?limit=50" \
  -H "X-Api-Key: YOUR_API_KEY"
```

Ответ:

```json
{
  "success": true,
  "data": {
    "messages": [
      {
        "id": 9123,
        "authorId": 20294,
        "text": "Релиз 24.500.0 готов",
        "createdAt": "2026-06-10T14:51:00+02:00",
        "isSystem": false
      }
    ],
    "hasNextPage": true
  }
}
```

## Поля сообщения

| Поле | Описание |
|------|---------|
| `id` | ID сообщения — используйте минимальный из страницы как `lastId` для следующей |
| `authorId` | Автор (`0` у системных сообщений) |
| `text` | Текст сообщения. Может содержать BB-коды Битрикс24 |
| `createdAt` | Дата создания, ISO 8601 |
| `isSystem` | Системное сообщение («задача поставлена», «срок изменён», …) — фильтруйте по этому флагу, если нужны только реплики людей |

## Что нужно знать перед работой

1. **Нужен скоуп `im` на стороне Битрикс24.** Эндпоинт читает чат через `im.*`-методы Битрикс24 — вебхук или OAuth-грант ключа должен включать скоуп `im` помимо `task`, иначе портал вернёт `insufficient_scope`.
2. **Доступ — по членству в чате.** Битрикс24 отдаёт сообщения, только если пользователь, от имени которого работает ключ, — участник чата задачи (постановщик, исполнитель, наблюдатель) или администратор портала.
3. **Сообщения идут от новых к старым.** Первый элемент — самое свежее сообщение. Пагинация курсором `lastId` уходит вглубь истории.
4. **404, если чата ещё нет.** Битрикс24 создаёт чат задачи не сразу — у задачи без единого сообщения чата может не быть (`TASK_CHAT_NOT_FOUND`).
5. **Старые порталы.** На порталах без современной `im.v2`-поверхности API прозрачно переключается на устаревший метод: страница там ограничена 50 сообщениями, а `hasNextPage` вычисляется по заполненности страницы.
6. **Комментарии и чат.** [`GET /v1/tasks/:taskId/comments`](../task-comments.md) возвращает только пользовательские комментарии. Этот эндпоинт — сырую ленту чата целиком, включая системные сообщения.

## Ошибки

| HTTP | Код | Причина |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | Нечисловой `taskId`, нечисловой или неположительный `limit` либо `lastId`. Значение `limit` больше 200 не ошибка — оно ограничивается до 200 |
| 403 | `SCOPE_DENIED` | У ключа нет скоупа `task` |
| 404 | `TASK_CHAT_NOT_FOUND` | У задачи нет чата (или задачи не существует) |
| 422 | `BITRIX_ERROR` | Ошибка Битрикс24: `insufficient_scope` (нет `im`), `ACCESS_ERROR` (не участник чата) |

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

- [Задачи](../tasks.md)
- [Комментарии задач](../task-comments.md)
- [Scrum](/docs/scrum)