# Task comments

Comments are a nested task resource. Each comment has an author, text, and creation time. The base path is `/v1/tasks/:taskId/comments`. All operations require an existing task (`:taskId`) in the Bitrix24 account.

Bitrix24 API: `tasks.task.chat.message.*`, `task.commentitem.*`
Scope: `task`

## Operations

- [Create comment](./task-comments/create.md) — `POST /v1/tasks/:taskId/comments`
- [List comments](./task-comments/list.md) — `GET /v1/tasks/:taskId/comments`
- [Get comment](./task-comments/get.md) — `GET /v1/tasks/:taskId/comments/:id`
- [Update comment](./task-comments/update.md) — `PATCH /v1/tasks/:taskId/comments/:id`
- [Delete comment](./task-comments/delete.md) — `DELETE /v1/tasks/:taskId/comments/:id`
- [Comment fields](./task-comments/fields.md) — `GET /v1/tasks/:taskId/comments/fields`
- [Download an attachment](./task-comments/file-download.md) — `GET /v1/tasks/:taskId/comments/:id/files/:fileId/download`
- [Batch comment operations](./task-comments/comments-batch.md) — `POST /v1/tasks/:taskId/comments/batch`

## Key fields

| Field | Description |
|------|---------|
| `id` | Comment identifier |
| `taskId` | Parent task ID (taken from the URL path) |
| `authorId` | Author. Employee list: `GET /v1/users` |
| `message` | Comment text, up to 65,535 characters. Supports BB-code `[USER=ID]Name[/USER]`, `[B]...[/B]`, `[QUOTE]...[/QUOTE]` and others |
| `createdAt` | Creation date and time, UTC ISO 8601 |
| `attachments` | Attached files. The key is always present; with no files it is an empty list. The bytes are served by [`GET /v1/tasks/:taskId/comments/:id/files/:fileId/download`](./task-comments/file-download.md) |

Full field list — [`GET /v1/tasks/:taskId/comments/fields`](./task-comments/fields.md).

## What to know before you start

1. **A task has two cards.** Bitrix24 runs two versions of the task card in parallel: the "new" one (chat-based) and the "old" one (with a comments block inside the card itself). The call is the same, but under the hood the API picks the working path depending on how the Bitrix24 account is configured. The differences show up in PATCH/DELETE — see below — and in the comment list: filtering and sorting by `AUTHOR_NAME` or `AUTHOR_EMAIL` are accepted on the old card only, while `offset` is honored and `meta.truncated` arrives only on the new one for a request with `filter` or a sort other than `ID`. Details — [List comments](./task-comments/list.md).
2. **PATCH and DELETE on the new card return 410 GONE.** On the new card, Bitrix24 has no public API for updating / deleting comments — it only posts new messages. On Bitrix24 accounts with the old card, update and delete keep working unchanged. The API returns `410 GONE` with a message and a hint if it hits the new card, and `200`/`204` on the old one.
3. **POST returns the real message `id`.** On the new card, after posting a comment the API runs an extra lookup in the task chat and returns the actual identifier. In rare cases (OAuth application + several identical messages in a row in the same chat) `id` may come back as `null` — then find the comment via `GET /v1/tasks/:taskId/comments`.
4. **System messages are not returned.** The task chat contains notifications like "task created", "deadline changed" — `GET /v1/tasks/:taskId/comments` skips them. The list contains only user comments.
5. **`meta.total` is counted in two ways.** For a request without `filter` and with a sort by `ID`, it is an estimate: if the current page has fewer items than `limit`, then `total` equals the item count, otherwise it is the item count plus 1. Rely on `meta.hasMore` for pagination. On the new card with `filter` or a sort other than `ID`, it is the exact count of the matching comments within the scanned window, and `meta.truncated: true` means the scan window was exhausted and part of the history remains beyond it.
6. **The flat path `/v1/task-comments` does not exist.** All operations are available only in the form `/v1/tasks/:taskId/comments/...`. A call without the prefix returns `400 WRONG_PATH` with a hint.
7. **The list reads the chat whenever the task has one.** When a task has a chat, `GET /v1/tasks/:taskId/comments` returns the chat comments. Comments written before the Bitrix24 account moved to the new card were never migrated into the chat, so on such a task the list comes back empty even though the comments are still there in the comments block of the old card. Getting a comment by identifier and downloading an attachment check both stores, but they do NOT guarantee a hit: the lookup goes chat-first and the two stores' identifiers overlap numerically — see "A matching number means nothing" in [Download an attachment](./task-comments/file-download.md). If you know the comment `id`, use [`GET /v1/tasks/:taskId/comments/:id`](./task-comments/get.md) instead of relying on the list.

## Typical scenario

1. Find the task: [`GET /v1/tasks`](./tasks/list.md), or use the ID returned when the task was created.
2. Add a comment: [`POST /v1/tasks/:taskId/comments`](./task-comments/create.md) with `message`.
3. Show the discussion: [`GET /v1/tasks/:taskId/comments`](./task-comments/list.md) — supports `limit`, sorting and filtering by `ID`, `AUTHOR_ID` or `POST_DATE` on both cards.
4. To add comments in bulk — [`POST /v1/tasks/:taskId/comments/batch`](./task-comments/comments-batch.md) (up to 50 messages).

## Limits

| Limit | Value |
|-------|----------|
| Maximum characters in `message` | 65,535 |
| Maximum items per batch call | 50 |
| Page size `limit` | up to 200 |
| Rate limit | shared across the API — see [Limits and optimization](/docs/optimization) |

## See also

- [Tasks](./tasks.md)
- [Task time tracking](./tasks/time.md)
- [Employees](/docs/entities/users)
- [Batch](/docs/batch)
- [Limits and optimization](/docs/optimization)