Дела в CRM: обзор методов

В CRM дела используются для любых задач, связанных с клиентами: звонки, встречи, согласование документов.

Дела делятся на входящие и запланированные:

• Входящие — дела, поступившие от клиента, например письмо, звонок или чат. Для таких дел важно верно указать параметр DIRECTION = 1, чтобы сработал счетчик входящих дел CRM
• Запланированные — дела, которые создают сотрудники, например задачи или универсальные дела. В них можно указать срок выполнения, добавить связи с элементами CRM, с календарем, пригласить коллег, прикрепить файлы

Быстрый переход: все методы и события

Пользовательская документация: дела в CRM

Как выбрать вид делаКак выбрать вид дела

В CRM есть четыре вида дел. Они различаются тем, кто создает дело и насколько можно менять его карточку.

Вид дела	Кто создает	Когда использовать
Системное дело	Телефония, почта, чат или приложение методом crm.activity.add	Нужны звонок, письмо, встреча или дело со стандартной карточкой
Универсальное дело	Сотрудник в карточке элемента или приложение методом crm.activity.todo.add	Нужны срок, цвет, участники, переговорная и синхронизация с календарем
Конфигурируемое дело	Только приложение методом crm.activity.configurable.add	Нужен собственный внешний вид карточки дела с блоками и кнопками приложения
Дело пользовательского типа	Приложение методом crm.activity.add после регистрации типа	Нужны своя иконка и название типа дела в интерфейсе

Идентификаторы типов делИдентификаторы типов дел

Тип системного дела задает параметр TYPE_ID.

TYPE_ID	Тип дела
1	Встреча
2	Звонок
3	Задача
4	Письмо
5	Общее дело, используется при импорте событий календаря
6	Дело провайдера: универсальные и конфигурируемые дела, дела приложений

Направление дела задает параметр DIRECTION: 1 — входящее, 2 — исходящее. Направление актуально для звонков и писем, для встреч оно не используется.

Как начать работуКак начать работу

1. Определите элемент CRM, в таймлайне которого будет храниться дело: тип объекта передается в OWNER_TYPE_ID, идентификатор — в OWNER_ID. Значения типов смотрите в справочнике Тип объекта CRM.
2. Получите состав доступных полей методом crm.activity.fields.
3. Создайте дело методом нужного вида: crm.activity.add, crm.activity.todo.add или crm.activity.configurable.add.
4. Получите дело методом crm.activity.get или список дел элемента методом crm.activity.list.
5. Удалите ненужное дело методом crm.activity.delete.
6. Подпишитесь на события дел, чтобы отслеживать изменения в реальном времени.

Связи дел с другими элементами CRMСвязи дел с другими элементами CRM

Дела, связанные с элементами CRM, хранятся в таймлайне карточки элемента. Если у дела есть связь с несколькими элементами — например, письмо может быть привязано и к сделке и к контакту — оно будет храниться в таймлайнах всех связанных элементов.

Связи между делами и элементами CRM можно добавлять и удалять методами группы crm.activity.binding.*.

Системные делаСистемные дела

Системные дела CRM создает автоматически:

• дело звонка создает подключенная в Битрикс24 телефония. Для завершения звонка используйте метод telephony.externalcall.finish. Метод завершает звонок, создает дело в карточке элемента и возвращает идентификатор созданного дела в параметре CRM_ACTIVITY_ID
• дело письма создает почта. Когда на подключенный в Битрикс24 адрес приходит письмо от клиента, CRM проверяет, существует ли в базе клиент с e-mail из письма. По результатам проверки будет создано дело в карточке найденного элемента или новый клиент, в карточке которого появится дело

Чтобы создать, изменить или удалить системное дело, используйте группу методов crm.activity.*. При создании системного дела указывайте TYPE_ID, например для дела письма — TYPE_ID = 4. Значения остальных типов перечислены в блоке Идентификаторы типов дел.

Дела пользовательских типовДела пользовательских типов

Приложения могут регистрировать пользовательские типы дел: загрузить собственную иконку и указать название типа. Например, можно создать свой тип дел с иконкой и названием вашего приложения.

• Зарегистрировать тип дела — используйте методы группы crm.activity.type.*. При создании типа необходимо задать его кодовое обозначение в параметре TYPE_ID
• Создать дело с типом приложения — используйте группу методов системных дел crm.activity.add. При создании дела укажите кодовое обозначение пользовательского типа TYPE_ID, зарегистрированного для типа дел, в параметре PROVIDER_TYPE_ID

Универсальные делаУниверсальные дела

Универсальные дела — это тип дел с расширенными настройками: крайним сроком, цветом, участниками, переговорной и синхронизацией с календарем.

Создает дело метод crm.activity.todo.add, изменяет — crm.activity.todo.update. Отдельные методы меняют только одно свойство дела: крайний срок, описание, цвет или ответственного. Как выбрать нужный метод, описано в разделе Универсальные дела CRM.

Конфигурируемые делаКонфигурируемые дела

Конфигурируемые дела — это тип дел, создать который можно только из приложения. Для этого типа можно настроить внешний вид карточки дела и ее функционал:

• Структура конфигурируемого дела
• Бейджи конфигурируемого дела

Чтобы создать или изменить конфигурируемое дело, используйте группу методов crm.activity.configurable.*.

ВиджетыВиджеты

В дела можно встраивать приложения. Для встроек используют специальные места, в делах доступно одно — Пункт контекстного меню дела в карточке элемента CRM_XXX_ACTIVITY_TIMELINE_MENU.

Благодаря встройке можно будет использовать приложение, не покидая карточку элемента. Приложение будет открываться на той странице, которую вы укажете при регистрации встройки.

Дополнительные возможностиДополнительные возможности

Текстовые заметки можно добавлять к делам и удалять их. Используйте группу методов crm.timeline.note.*.

Контентные блоки можно добавлять к делам и удалять их. Используйте группу методов crm.activity.layout.blocks.*.

• Доступные контентные блоки

Обзор методов и событийОбзор методов и событий

Scope: crm

Кто может выполнять методы: в зависимости от метода

Общие методы и событияОбщие методы и события

Управление связями делУправление связями дел

Метод	Описание
crm.activity.binding.add	Добавляет связь дела с элементом CRM
crm.activity.binding.list	Возвращает список связей дела
crm.activity.binding.move	Переносит связь дела на другой элемент CRM
crm.activity.binding.delete	Удаляет связь дела с элементом CRM

Пользовательские типы делПользовательские типы дел

Метод	Описание
crm.activity.type.add	Регистрирует пользовательский тип дела с указанием названия и иконки
crm.activity.type.list	Получает список пользовательских типов дел
crm.activity.type.delete	Удаляет пользовательский тип дела

Универсальное делоУниверсальное дело

Метод	Описание
crm.activity.todo.add	Создает универсальное дело
crm.activity.todo.update	Обновляет универсальное дело
crm.activity.todo.updateColor	Изменяет цвет
crm.activity.todo.updateDeadline	Изменяет крайний срок
crm.activity.todo.updateDescription	Изменяет описание
crm.activity.todo.updateResponsibleUser	Изменяет ответственного

Конфигурируемое делоКонфигурируемое дело

Метод	Описание
crm.activity.configurable.add	Добавляет новое конфигурируемое дело в таймлайн
crm.activity.configurable.update	Обновляет конфигурируемое дело
crm.activity.configurable.get	Получает информацию о деле по идентификатору

Бейджи конфигурируемого делаБейджи конфигурируемого дела

Метод	Описание
crm.activity.badge.add	Добавляет новый бейдж
crm.activity.badge.get	Получает информацию о бейдже
crm.activity.badge.list	Получает список бейджей
crm.activity.badge.delete	Удаляет бейдж по коду

Дополнительные контентные блокиДополнительные контентные блоки

Метод	Описание
crm.activity.layout.blocks.set	Устанавливает набор дополнительных контентных блоков в дело
crm.activity.layout.blocks.get	Получает установленный приложением набор дополнительных контентных блоков в деле
crm.activity.layout.blocks.delete	Удаляет установленный приложением набор дополнительных контентных блоков для дела