REST: crm.activity (дела и коммуникации)

Дела (activity) — это запланированные и завершённые действия в таймлайне CRM: звонки, встречи, письма и задачи-напоминания. Семейство crm.activity.* позволяет из внешних систем создавать эти события, привязывать их к сделкам и контактам и фиксировать коммуникации клиента.

Что такое дело в CRM

Дело всегда привязано к «владельцу» — сделке, лиду, контакту или компании — через пару полей OWNER_TYPE_ID и OWNER_ID. Тип самого дела задаёт поле TYPE_ID.

Владелец задаётся константами CCrmOwnerType: лид — 1, сделка — 2, контакт — 3, компания — 4. Полный перечень полей возвращает crm.activity.fields.

Важно понимать логику дел в жизненном цикле сущности. Незавершённое дело с ближайшим дедлайном формирует «счётчик» у ответственного менеджера — именно поэтому корректное заполнение RESPONSIBLE_ID и DEADLINE напрямую влияет на то, увидит ли сотрудник задачу в своём списке дел. Завершённые дела остаются в таймлайне как история взаимодействий и используются в отчётах по активности отдела продаж. Таким образом, через crm.activity внешняя система не просто пишет лог, а полноценно управляет рабочей нагрузкой менеджеров и аналитикой коммуникаций.

Создание дела: crm.activity.add

Минимальный запрос на создание звонка, привязанного к сделке 340:

POST /rest/1/xxxxxxxx/crm.activity.add.json
{
  "fields": {
    "OWNER_TYPE_ID": 2,
    "OWNER_ID": 340,
    "TYPE_ID": 2,
    "SUBJECT": "Исходящий звонок по заявке",
    "DESCRIPTION": "Согласовали дату отгрузки",
    "DIRECTION": 2,
    "COMPLETED": "Y",
    "RESPONSIBLE_ID": 1,
    "COMMUNICATIONS": [
      { "VALUE": "+79001234567", "ENTITY_ID": 145, "ENTITY_TYPE_ID": 3 }
    ]
  }
}

Поле DIRECTION задаёт направление: 1 — входящее, 2 — исходящее. COMPLETED = Y отмечает дело выполненным; для запланированного дела передайте N и заполните START_TIME / END_TIME.

Поле COMMUNICATIONS

Именно COMMUNICATIONS связывает дело с конкретным каналом клиента — номером телефона или почтой. Каждый элемент массива описывает участника коммуникации.

• VALUE — значение (номер, e-mail);
• ENTITY_ID — ID сущности-собеседника;
• ENTITY_TYPE_ID — её тип (контакт 3, компания 4);
• TYPE — PHONE или EMAIL.

Один и тот же массив может содержать несколько участников — например, если письмо ушло сразу на два адреса клиента. При этом значение из COMMUNICATIONS Битрикс24 сопоставляет с уже известными контактами: если номер телефона совпал с полем контакта, дело автоматически привяжется и к нему. Поэтому перед созданием дела полезно убедиться, что коммуникации клиента заведены в его карточке — иначе связь окажется формальной, а фильтры по конкретному собеседнику работать не будут.

Современные дела: todo и настраиваемые активности

Помимо классического crm.activity.add, в актуальных версиях Битрикс24 появились специализированные методы для дел нового таймлайна:

• crm.activity.todo.add — быстрое создание дела-напоминания «Сделать» с дедлайном;
• crm.activity.todo.update — обновление такого дела;
• crm.activity.configurable.add — настраиваемое дело с произвольной разметкой блоков в карточке.

Для интеграции звонков сторонней телефонии используется связка с провайдерами: дело создаётся с PROVIDER_ID и PROVIDER_TYPE_ID, что позволяет отличать источники активностей и корректно рисовать их в ленте.

Выборка и завершение дел

Список дел получают через crm.activity.list с фильтром по владельцу. Так выглядит выборка всех незавершённых дел по сделке:

POST /rest/1/xxxxxxxx/crm.activity.list.json
{
  "filter": { "OWNER_TYPE_ID": 2, "OWNER_ID": 340, "COMPLETED": "N" },
  "select": ["ID", "SUBJECT", "TYPE_ID", "DEADLINE", "RESPONSIBLE_ID"],
  "order": { "DEADLINE": "ASC" }
}

Отметить дело выполненным можно двумя способами: обновить COMPLETED = Y через crm.activity.update или использовать поля дедлайна. Удаление — crm.activity.delete. Постраничность и здесь работает через параметр start с шагом 50.

При построении отчётов о нагрузке помните, что crm.activity.list отдаёт дела всех типов сразу — звонки, письма и встречи. Чтобы получить, например, только звонки за период, комбинируйте в фильтре TYPE_ID и диапазон по CREATED с операторами сравнения >= и <=. Для выборок по нескольким ответственным передавайте в фильтр массив идентификаторов в RESPONSIBLE_ID. А если внешней аналитике нужны все дела разом, эффективнее не листать постранично, а идти по возрастанию ID с фильтром «больше последнего обработанного» — это стабильнее при параллельном изменении данных.

Практические рекомендации

Несколько правил, которые экономят время при интеграции дел:

1. Всегда заполняйте RESPONSIBLE_ID — иначе дело повиснет без ответственного;
2. Для истории коммуникаций создавайте дело сразу с COMPLETED = Y, для планов — с дедлайном и N;
3. Не забывайте COMMUNICATIONS, иначе дело не свяжется с каналом клиента;
4. Подписывайтесь на событие ONCRMACTIVITYADD вебхуком, если внешняя система должна реагировать на новые дела.

Итог

Метод crm.activity — это универсальный инструмент фиксации активности в CRM: от простого напоминания до записи телефонного разговора. Ключевые элементы — тип дела (TYPE_ID), привязка к владельцу (OWNER_TYPE_ID / OWNER_ID) и связь с каналом клиента (COMMUNICATIONS). Для нового таймлайна используйте crm.activity.todo.* и настраиваемые активности.

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