REST: активности и таймлайн

Активности (дела) — это звонки, встречи, письма и задачи, привязанные к элементам CRM Битрикс24. Через семейство методов crm.activity.* вы создаёте и закрываете дела, а таймлайн показывает историю карточки. Разберём модель данных, привязки и типовые запросы.

Модель дел и место в таймлайне

Активность (по-русски «дело») в Битрикс24 — это единица работы, привязанная к владельцу: лиду, сделке, контакту или компании. В таймлайне карточки дела отображаются как запланированные или завершённые события, вперемешку с комментариями, автоматическими записями роботов и историей звонков.

Ключевые методы семейства:

• crm.activity.add — создать дело;
• crm.activity.get — получить одно дело по ID;
• crm.activity.list — выборка с фильтром, сортировкой и постраничностью;
• crm.activity.update — изменить, в том числе закрыть дело;
• crm.activity.delete — удалить;
• crm.activity.fields — описание всех полей;
• crm.activity.binding.* — управление привязками дела к нескольким сущностям.

Типы дел, владелец и направление

Поведение дела задают три группы полей: тип, владелец и направление коммуникации.

Для звонков и писем важна пара PROVIDER_ID и PROVIDER_TYPE_ID — они определяют, каким сервисом создано дело (например, CRM_EMAIL, VOXIMPLANT_CALL или ваше REST-приложение REST_APP). Собеседники дела перечисляются в массиве COMMUNICATIONS.

Создание дела: пример запроса

Минимальный звонок-напоминание на сделке. Обратите внимание на структуру COMMUNICATIONS, где указывается контакт-собеседник и его тип.

POST https://portal.bitrix24.ru/rest/1/xxxxxx/crm.activity.add.json

{
  "fields": {
    "OWNER_TYPE_ID": 2,
    "OWNER_ID": 145,
    "TYPE_ID": 2,
    "SUBJECT": "Перезвонить по КП",
    "DESCRIPTION": "Уточнить сроки поставки",
    "DESCRIPTION_TYPE": 1,
    "DIRECTION": 2,
    "START_TIME": "2026-07-17T10:00:00+03:00",
    "END_TIME":   "2026-07-17T10:15:00+03:00",
    "COMPLETED": "N",
    "RESPONSIBLE_ID": 12,
    "COMMUNICATIONS": [
      { "VALUE": "+79001234567", "ENTITY_ID": 88, "ENTITY_TYPE_ID": 3 }
    ]
  }
}

Метод вернёт ID созданного дела. Чтобы закрыть его, вызовите crm.activity.update с COMPLETED: "Y" — в таймлайне событие переедет из блока «Запланировано» в историю. Поле DESCRIPTION_TYPE задаёт формат описания: 1 — обычный текст, 3 — BBCode; если вы передаёте размеченный текст как обычный, теги отобразятся буквально. Для писем и звонков вместо ручного TYPE_ID обычно указывают провайдера, тогда дело получает правильную иконку и поведение в интерфейсе CRM.

Выборка дел: фильтр и постраничность

Метод crm.activity.list принимает filter, select, order и системный start. Получим все незавершённые звонки по сделке:

{
  "order":  { "START_TIME": "ASC" },
  "filter": {
    "OWNER_TYPE_ID": 2,
    "OWNER_ID": 145,
    "COMPLETED": "N",
    "TYPE_ID": 2
  },
  "select": [ "ID", "SUBJECT", "START_TIME", "RESPONSIBLE_ID", "COMMUNICATIONS" ]
}

Ответ содержит блок total и постраничный next. За один вызов возвращается до 50 записей — для следующей страницы передавайте start: 50, затем 100 и так далее.

Привязки к нескольким сущностям

Одно дело может относиться сразу к сделке и её контакту. Владелец задаёт основную привязку, а дополнительные добавляются методами crm.activity.binding.add, crm.activity.binding.delete и crm.activity.binding.list.

1. Создаёте дело с владельцем-сделкой;
2. Добавляете привязку к контакту, чтобы дело появилось и в его таймлайне;
3. При удалении элемента лишние привязки чистятся автоматически.

// crm.activity.binding.add
{
  "activityId": 9021,
  "entityTypeId": 3,
  "entityId": 88
}

Такой подход удобен, когда письмо адресовано контакту, но должно быть видно в сделке — без дублирования самой активности.

Таймлайн и комментарии

Сам таймлайн формируется из дел, историй и комментариев. Комментарии — отдельная сущность с методами crm.timeline.comment.add, crm.timeline.comment.list, crm.timeline.comment.update, crm.timeline.comment.delete. Пример добавления записи от имени пользователя:

// crm.timeline.comment.add
{
  "fields": {
    "ENTITY_ID": 145,
    "ENTITY_TYPE": "deal",
    "COMMENT": "Клиент подтвердил бюджет",
    "AUTHOR_ID": 12
  }
}

Через дела в таймлайн попадают структурированные события (звонок, письмо), а через комментарии — свободные заметки менеджера. Оба источника читаются одним визуальным блоком в карточке.

Практические нюансы интеграций

• Часовой пояс. Поля времени принимают ISO-8601 со смещением; храните UTC и конвертируйте в пояс портала при выводе.
• Ответственный. Если не передать RESPONSIBLE_ID, дело закрепится за пользователем вебхука — это частая причина «потерянных» задач.
• Права. Вебхук работает от лица конкретного сотрудника: он не увидит дела, недоступные ему по правам CRM.
• События. На создание и обновление дел подписываются онлайн-события ONCRMACTIVITYADD и ONCRMACTIVITYUPDATE.
• Пакетность. Массовую загрузку истории коммуникаций выполняйте через batch — до 50 команд за один HTTP-запрос.

Итог

Дела crm.activity.* и комментарии таймлайна вместе дают полную историю работы с клиентом: запланированные звонки, отправленные письма и заметки менеджера в одной ленте. Ключ к корректной интеграции — правильно проставленные OWNER_TYPE_ID, TYPE_ID и COMMUNICATIONS, аккуратная постраничность и учёт лимитов REST.

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