# Timeline comments

Manage CRM timeline comments: recording operator notes, negotiation history and other context for deals, leads, contacts, companies and other entities. Each comment is attached to a specific CRM record via the `entityType` + `entityId` pair.

Bitrix24 API: `crm.timeline.comment.*`
Scope: `crm`

## Operations

- [Add comment](./timelines/create.md) — `POST /v1/timelines`
- [List comments](./timelines/list.md) — `GET /v1/timelines`
- [Get comment](./timelines/get.md) — `GET /v1/timelines/:id`
- [Update comment](./timelines/update.md) — `PATCH /v1/timelines/:id`
- [Delete comment](./timelines/delete.md) — `DELETE /v1/timelines/:id`
- [Search comments](./timelines/search.md) — `POST /v1/timelines/search`
- [Comment fields](./timelines/fields.md) — `GET /v1/timelines/fields`

## Pinning, bindings, notes

The Bitrix24 operations in the `crm.timeline.item.*`, `crm.timeline.bindings.*`, `crm.timeline.note.*` families are universal — they work with any timeline element by `id + ownerTypeId + ownerId`. The same actions therefore apply to comments as to log entries. Below are copies of 8 endpoints from the [`/v1/timeline-logs`](/docs/timeline-logs) section, mounted on the `/v1/timelines` root:

| Method | Path | B24 method | Purpose |
|------|------|-----------|------------|
| POST | `/v1/timelines/:id/pin` | `crm.timeline.item.pin` | Pin the comment to the top of the timeline |
| POST | `/v1/timelines/:id/unpin` | `crm.timeline.item.unpin` | Remove the pin |
| POST | `/v1/timelines/:id/bind` | `crm.timeline.bindings.bind` | Additionally bind the comment to another entity (e.g. a contact) |
| POST | `/v1/timelines/:id/unbind` | `crm.timeline.bindings.unbind` | Remove one of the bindings |
| GET | `/v1/timelines/:id/bindings` | `crm.timeline.bindings.list` | Get all bindings of the comment |
| POST | `/v1/timelines/:id/note` | `crm.timeline.note.save` | Save a note (text annotation) on the comment |
| GET | `/v1/timelines/:id/note` | `crm.timeline.note.get` | Read the note |
| DELETE | `/v1/timelines/:id/note` | `crm.timeline.note.delete` | Delete the note |

Full request / response signatures and examples are in the mirror of the [`/v1/timeline-logs`](/docs/timeline-logs) section: [pins](/docs/timeline-logs/pins), [bindings](/docs/timeline-logs/bindings), [notes](/docs/timeline-logs/notes). The request body, response format and error codes are identical — only the path prefix differs.

## Key fields

| Field | Description |
|------|---------|
| `entityType` | Type of the parent CRM record: `deal`, `lead`, `contact`, `company` or `DYNAMIC_<entityTypeId>` for smart processes (e.g. `DYNAMIC_174`). Required on creation and in the filter |
| `entityId` | Parent record ID. The source depends on the type: `GET /v1/deals`, `GET /v1/leads`, `GET /v1/contacts`, `GET /v1/companies`, `GET /v1/items/:entityTypeId` (smart-process items). Required on creation and in the filter |
| `comment` | Comment text. Required on creation |
| `authorId` | Author ID. User data by ID: `GET /v1/users/:id` |
| `createdAt` | Creation date (read-only) |

Full field list — [`GET /v1/timelines/fields`](./timelines/fields.md).

## What you need to know before working

1. **A filter by `entityType` + `entityId` is required.** The comment list is queried only in the context of a specific parent record — there is no global list of "all comments in the Bitrix24 account". A request without these fields returns `400 MISSING_REQUIRED_FILTER`.
2. **Creation requires 3 fields:** `entityType`, `entityId`, `comment`. The author is set from the API key owner, the date by the server.
3. **A comment is updated by `id`**, while `entityType` and `entityId` are fixed on creation and cannot be changed afterward.
4. **`entityType` values are string identifiers of CRM types.** Numeric CRM codes (`entityTypeId`) are not valid for `entityType`: they return `BITRIX_ERROR Access denied.`. Use `deal`, `lead`, `contact`, `company` or `DYNAMIC_<entityTypeId>` for smart processes (e.g. `DYNAMIC_174` for a smart process with `entityTypeId: 174` from [`GET /v1/smart-processes`](/docs/entities/smart-processes/list)). In the API response `entityType` is returned in lowercase (`dynamic_174`).

## Typical scenario

1. Find the parent record: [`GET /v1/deals`](/docs/entities/deals/list), [`GET /v1/leads`](/docs/entities/leads/list), [`GET /v1/contacts`](/docs/entities/contacts), [`GET /v1/companies`](/docs/entities/companies) or [`GET /v1/items/:entityTypeId`](/docs/entities/items/list) for smart-process items.
2. View its comments: [`GET /v1/timelines?filter[entityType]=deal&filter[entityId]=741`](./timelines/list.md).
3. Add a new comment: [`POST /v1/timelines`](./timelines/create.md).
4. If needed, change the text: [`PATCH /v1/timelines/:id`](./timelines/update.md), delete: [`DELETE /v1/timelines/:id`](./timelines/delete.md).

## Limits

| Limit | Value |
|-------|----------|
| Maximum records per request | 5000 (`limit ≤ 5000`) |
| Auto-pagination | enabled when `limit > 50` |
| `offset` on large result sets | `limit ≤ 500` recommended when `offset ≥ 2500` |
| Batch requests | up to 50 operations in [`POST /v1/batch`](/docs/batch) |
| Rate limit | shared across the Vibe API — see [Limits and optimization](/docs/optimization) |

## See also

- [Deals](./deals.md), [Leads](./leads.md), [Contacts](./contacts.md), [Companies](./companies.md) — typical parent entities
- [Timeline logs](/docs/timeline-logs) — read the full activity history of a CRM record (includes not only comments, but also system events)
- [Filtering syntax](/docs/filtering)
- [Batch](/docs/batch) — bulk operations
- [Entities reference](/docs/entities-index)