REST: crm.timeline.comment

Комментарии таймлайна — это текстовые записи в ленте карточки лида, сделки, контакта или компании. Семейство crm.timeline.comment.* добавляет, читает, правит и удаляет их, а также прикрепляет файлы. Разберём поля, типы владельца и вложения.

Методы семейства

Комментарий — самостоятельная сущность таймлайна, отдельная от дел (crm.activity). Набор методов стандартный для CRM:

• crm.timeline.comment.add — добавить комментарий;
• crm.timeline.comment.get — получить один по ID;
• crm.timeline.comment.list — список по владельцу;
• crm.timeline.comment.update — изменить текст или вложения;
• crm.timeline.comment.delete — удалить;
• crm.timeline.comment.fields — описание полей.

Комментарии удобны для фиксации договорённостей, автоматических отметок от интеграций и переноса истории переписки из внешних систем — в отличие от дел, они не требуют типа, направления и времени.

Поля комментария

Структура записи компактна. Основные поля:

Добавление комментария

Добавим запись в таймлайн сделки от имени конкретного сотрудника:

POST /rest/1/xxxxxx/crm.timeline.comment.add.json

{
  "fields": {
    "ENTITY_ID": 145,
    "ENTITY_TYPE": "deal",
    "COMMENT": "Клиент согласовал спецификацию, ждём оплату",
    "AUTHOR_ID": 12
  }
}

Метод вернёт ID созданного комментария. Если AUTHOR_ID не передан, автором станет пользователь вебхука. В тексте COMMENT можно использовать BBCode: переносы строк, ссылки [URL] и упоминания пользователей [USER=12]Имя[/USER].

Вложения файлов

К комментарию можно прикрепить файлы через поле FILES. Каждый элемент — пара «имя файла» и содержимое в base64:

// crm.timeline.comment.add с файлом
{
  "fields": {
    "ENTITY_ID": 145,
    "ENTITY_TYPE": "deal",
    "COMMENT": "Договор во вложении",
    "FILES": [
      { "fileData": [ "dogovor.pdf", "JVBERi0xLjQKJ..." ] }
    ]
  }
}

Содержимое кодируется в base64 без префикса data-URL. Размер запроса ограничен, поэтому крупные файлы лучше сначала загрузить на диск и прикреплять ссылкой либо дробить передачу.

Чтение и правка

Список комментариев по владельцу возвращает crm.timeline.comment.list с фильтром по паре «тип + ID»:

// crm.timeline.comment.list
{
  "filter": { "ENTITY_ID": 145, "ENTITY_TYPE": "deal" },
  "order":  { "CREATED": "DESC" }
}

Правка текста — через crm.timeline.comment.update с указанием id и новых fields. Удаление — crm.timeline.comment.delete по id. Права работают как везде в CRM: пользователь вебхука должен иметь доступ к владельцу комментария, иначе операция вернёт ошибку доступа.

Практика применения

• Логи интеграций. Записывайте в таймлайн ключевые события внешних систем — статус оплаты, номер отгрузки — так менеджер видит контекст прямо в карточке.
• Перенос переписки. При миграции из другой CRM импортируйте историю как комментарии с корректным AUTHOR_ID и датой.
• Разделяйте роли. Структурированные коммуникации (звонки, письма) ведите через дела, а свободные заметки — через комментарии.
• Не спамьте. Технические сообщения без ценности для менеджера лучше писать в отдельный лог, а не в таймлайн.

Такое разделение держит ленту карточки читаемой и полезной, а не превращает её в поток служебных записей.

Итог

Методы crm.timeline.comment.* дают простой и надёжный способ добавлять записи в ленту карточки: текст с BBCode, вложения в base64 и указание автора. Ключевые тонкости — строковый ENTITY_TYPE вместо числового id, лимиты на размер файлов и соблюдение прав доступа.

Мы в B2Bsite используем комментарии таймлайна, чтобы показывать менеджерам события из сайта и учётных систем прямо в сделке: оплаты, отгрузки, статусы заявок. Если хотите, чтобы карточка клиента отражала весь путь без переключения между системами, — поможем настроить такой обмен.