# Комментарии задач

Комментарии — вложенный ресурс задачи. У каждого комментария есть автор, текст и время создания. Базовый путь — `/v1/tasks/:taskId/comments`. Все операции требуют существующей задачи (`:taskId`) на портале.

Битрикс24 API: `tasks.task.chat.message.*`, `task.commentitem.*`
Скоуп: `task`

## Операции

- [Создать комментарий](./task-comments/create.md) — `POST /v1/tasks/:taskId/comments`
- [Список комментариев](./task-comments/list.md) — `GET /v1/tasks/:taskId/comments`
- [Получить комментарий](./task-comments/get.md) — `GET /v1/tasks/:taskId/comments/:id`
- [Обновить комментарий](./task-comments/update.md) — `PATCH /v1/tasks/:taskId/comments/:id`
- [Удалить комментарий](./task-comments/delete.md) — `DELETE /v1/tasks/:taskId/comments/:id`
- [Поля комментария](./task-comments/fields.md) — `GET /v1/tasks/:taskId/comments/fields`
- [Пакет операций](./task-comments/comments-batch.md) — `POST /v1/tasks/:taskId/comments/batch`

## Ключевые поля

| Поле | Описание |
|------|---------|
| `id` | Идентификатор комментария |
| `taskId` | ID родительской задачи (берётся из пути URL) |
| `authorId` | Автор. Список сотрудников: `GET /v1/users` |
| `message` | Текст комментария, до 65 535 символов. Поддерживает BB-код `[USER=ID]Имя[/USER]`, `[B]...[/B]`, `[QUOTE]...[/QUOTE]` и другие |
| `createdAt` | Дата и время создания, UTC ISO 8601 |

Полный список полей — [`GET /v1/tasks/:taskId/comments/fields`](./task-comments/fields.md).

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

1. **У задачи две карточки.** В Битрикс24 параллельно живут две версии карточки задачи: «новая» (на базе чата) и «старая» (с блоком комментариев внутри самой карточки). Вызов одинаковый, но под капотом API сам выбирает рабочий путь в зависимости от того, как настроен портал. Различия видны в PATCH/DELETE — см. ниже — и в списке комментариев: фильтр и сортировка по `AUTHOR_NAME` или `AUTHOR_EMAIL` принимаются только на старой карточке, а `offset` учитывается и `meta.truncated` приходит только на новой при запросе с `filter` или сортировкой не по `ID`. Подробности — [Список комментариев](./task-comments/list.md).
2. **PATCH и DELETE на новой карточке возвращают 410 GONE.** На новой карточке Битрикс24 нет публичного API обновления / удаления комментариев — он отправляет только новые сообщения. На порталах со старой карточкой обновление и удаление продолжают работать без изменений. API возвращает `410 GONE` с текстом и подсказкой, если попал на новую карточку, и `200`/`204` — на старой.
3. **POST возвращает реальный `id` сообщения.** На новой карточке после отправки комментария API выполняет дополнительный поиск по чату задачи и возвращает фактический идентификатор. В редком случае (OAuth-приложение + несколько одинаковых сообщений подряд в одном чате) `id` может прийти как `null` — тогда найдите комментарий через `GET /v1/tasks/:taskId/comments`.
4. **Системные сообщения не возвращаются.** Чат задачи содержит уведомления типа «задача поставлена», «срок изменён» — `GET /v1/tasks/:taskId/comments` их пропускает. В списке только пользовательские комментарии.
5. **`meta.total` считается двумя способами.** На запросе без `filter` и с сортировкой по `ID` это оценка: если в текущей странице меньше элементов, чем `limit`, то `total` равен числу элементов, иначе — `+1`. Опирайтесь на `meta.hasMore` для пагинации. На новой карточке с `filter` или сортировкой не по `ID` — точное число подошедших под фильтр комментариев в пределах просмотренного окна, а `meta.truncated: true` говорит, что окно исчерпано и за его границей осталась часть истории.
6. **Плоский путь `/v1/task-comments` не существует.** Все операции — только в виде `/v1/tasks/:taskId/comments/...`. Вызов без префикса вернёт `400 WRONG_PATH` с подсказкой.

## Типичный сценарий

1. Найти задачу: [`GET /v1/tasks`](./tasks/list.md) или прямой ID из создания задачи.
2. Добавить комментарий: [`POST /v1/tasks/:taskId/comments`](./task-comments/create.md) с `message`.
3. Показать обсуждение: [`GET /v1/tasks/:taskId/comments`](./task-comments/list.md) — поддерживает `limit`, сортировку и фильтр по `ID`, `AUTHOR_ID` или `POST_DATE` на обеих карточках.
4. Если нужно массовое добавление — [`POST /v1/tasks/:taskId/comments/batch`](./task-comments/comments-batch.md) (до 50 сообщений).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Максимум символов в `message` | 65 535 |
| Максимум элементов в одном batch-вызове | 50 |
| Размер страницы `limit` | до 200 |
| Rate limit | общий для API — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [Задачи](./tasks.md)
- [Учёт времени задач](./tasks/time.md)
- [Сотрудники](/docs/entities/users)
- [Batch](/docs/batch)
- [Лимиты и оптимизация](/docs/optimization)