# 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`) on 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`
- [Batch 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 |

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 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 over the task chat and returns the actual identifier. In a rare case (OAuth app + 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 — `+1`. Rely on `meta.hasMore` for pagination. On the new card with `filter` or a sort other than `ID` — the exact count of the matching comments within the scanned window, and `meta.truncated: true` says the window was exhausted and part of the history stayed beyond its edge.
6. **The flat path `/v1/task-comments` does not exist.** All operations are only in the form `/v1/tasks/:taskId/comments/...`. A call without the prefix returns `400 WRONG_PATH` with a hint.

## Typical scenario

1. Find the task: [`GET /v1/tasks`](./tasks/list.md) or a direct ID from task creation.
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. For bulk addition — [`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 for the API — see [Limits and optimization](/docs/optimization) |

## See also

- [Tasks](./tasks.md) — parent entity
- [Task time tracking](./tasks/time.md) — another nested task resource
- [Employees](/docs/entities/users) — source of `authorId`
- [Batch requests](/docs/batch) — bulk operations via the universal `POST /v1/batch`
- [Limits and optimization](/docs/optimization) — rate limits