# Комментарии таймлайна

Управление комментариями таймлайна CRM: запись заметок оператора, истории переговоров и прочего контекста к сделкам, лидам, контактам, компаниям и другим сущностям. Каждый комментарий привязан к конкретной записи CRM через пару `entityType` + `entityId`.

Битрикс24 API: `crm.timeline.comment.*`
Скоуп: `crm`

## Операции

- [Добавить комментарий](./timelines/create.md) — `POST /v1/timelines`
- [Список комментариев](./timelines/list.md) — `GET /v1/timelines`
- [Получить комментарий](./timelines/get.md) — `GET /v1/timelines/:id`
- [Обновить комментарий](./timelines/update.md) — `PATCH /v1/timelines/:id`
- [Удалить комментарий](./timelines/delete.md) — `DELETE /v1/timelines/:id`
- [Поиск комментариев](./timelines/search.md) — `POST /v1/timelines/search`
- [Поля комментария](./timelines/fields.md) — `GET /v1/timelines/fields`
- [Скачать вложение](./timelines/file-download.md) — `GET /v1/timelines/:commentId/files/:fileRef/download`

## Закрепление, привязки, заметки

Операции Bitrix24 семейств `crm.timeline.item.*`, `crm.timeline.bindings.*`, `crm.timeline.note.*` универсальны — работают с любым элементом таймлайна по `id + ownerTypeId + ownerId`. Поэтому к комментариям применимы те же действия, что и к лог-записям. Ниже — копии 8 эндпоинтов из раздела [`/v1/timeline-logs`](/docs/timeline-logs), смонтированные на корне `/v1/timelines`:

| Метод | Путь | B24-метод | Назначение |
|------|------|-----------|------------|
| POST | `/v1/timelines/:id/pin` | `crm.timeline.item.pin` | Закрепить комментарий поверх таймлайна |
| POST | `/v1/timelines/:id/unpin` | `crm.timeline.item.unpin` | Снять закрепление |
| POST | `/v1/timelines/:id/bind` | `crm.timeline.bindings.bind` | Дополнительно привязать комментарий к другой сущности (например, контакту) |
| POST | `/v1/timelines/:id/unbind` | `crm.timeline.bindings.unbind` | Снять одну из привязок |
| GET | `/v1/timelines/:id/bindings` | `crm.timeline.bindings.list` | Получить все привязки комментария |
| POST | `/v1/timelines/:id/note` | `crm.timeline.note.save` | Сохранить заметку (текстовое примечание) на комментарии |
| GET | `/v1/timelines/:id/note` | `crm.timeline.note.get` | Прочитать заметку |
| DELETE | `/v1/timelines/:id/note` | `crm.timeline.note.delete` | Удалить заметку |

Полные сигнатуры запросов / ответов и примеры — в зеркале раздела [`/v1/timeline-logs`](/docs/timeline-logs): [pins](/docs/timeline-logs/pins), [bindings](/docs/timeline-logs/bindings), [notes](/docs/timeline-logs/notes). Тело запроса, формат ответа и коды ошибок идентичны — отличается только префикс пути.

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

| Поле | Описание |
|------|---------|
| `entityType` | Тип родительской записи CRM: `deal`, `lead`, `contact`, `company` или `DYNAMIC_<entityTypeId>` для смарт-процессов (например `DYNAMIC_174`). Обязателен при создании и в фильтре |
| `entityId` | ID родительской записи. Источник зависит от типа: `GET /v1/deals`, `GET /v1/leads`, `GET /v1/contacts`, `GET /v1/companies`, `GET /v1/items/:entityTypeId` (элементы смарт-процессов). Обязателен при создании и в фильтре |
| `comment` | Текст комментария. Обязателен при создании |
| `authorId` | ID автора. Данные пользователя по ID: `GET /v1/users/:id` |
| `createdAt` | Дата создания (только чтение) |

Полный список полей — [`GET /v1/timelines/fields`](./timelines/fields.md).

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

1. **Фильтр по `entityType` + `entityId` обязателен.** Список комментариев выбирается только в контексте конкретной родительской записи — глобального списка «всех комментариев портала» нет. Запрос без этих полей возвращает `400 MISSING_REQUIRED_FILTER`.
2. **Для создания нужно 3 поля:** `entityType`, `entityId`, `comment`. Автор проставляется по владельцу API-ключа, дата — сервером.
3. **Комментарий обновляется по `id`**, а `entityType` и `entityId` фиксируются при создании и после обновлению не подлежат.
4. **Значения `entityType` — строковые идентификаторы CRM-типов.** Числовые коды CRM (`entityTypeId`) для `entityType` не подходят: они возвращают `BITRIX_ERROR Access denied.`. Используйте `deal`, `lead`, `contact`, `company` или `DYNAMIC_<entityTypeId>` для смарт-процессов (например, `DYNAMIC_174` для смарт-процесса с `entityTypeId: 174` из [`GET /v1/smart-processes`](/docs/entities/smart-processes/list)). В ответе API `entityType` возвращается в нижнем регистре (`dynamic_174`).

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

1. Найти родительскую запись: [`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) или [`GET /v1/items/:entityTypeId`](/docs/entities/items/list) для элементов смарт-процессов.
2. Посмотреть её комментарии: [`GET /v1/timelines?filter[entityType]=deal&filter[entityId]=741`](./timelines/list.md).
3. Добавить новый комментарий: [`POST /v1/timelines`](./timelines/create.md).
4. При необходимости изменить текст: [`PATCH /v1/timelines/:id`](./timelines/update.md), удалить: [`DELETE /v1/timelines/:id`](./timelines/delete.md).

## Лимиты

| Лимит | Значение |
|-------|----------|
| Максимум записей на запрос | 5000 (`limit ≤ 5000`) |
| Авто-пагинация | включается при `limit > 50` |
| `offset` на больших выборках | рекомендуется `limit ≤ 500` при `offset ≥ 2500` |
| Batch-запросы | до 50 операций в [`POST /v1/batch`](/docs/batch) |
| Rate limit | общий для API Вайбкод — см. [Лимиты и оптимизация](/docs/optimization) |

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

- [Сделки](./deals.md)
- [Лиды](./leads.md)
- [Контакты](./contacts.md)
- [Компании](./companies.md)
- [Таймлайн CRM](/docs/timeline-logs)
- [Синтаксис фильтрации](/docs/filtering)
- [Batch](/docs/batch)
- [Справочник сущностей](/docs/entities-index)