Поиск писем в сущности

Активити (робот) "Поиск писем" предназначено для использования в роботах и может быть полезно в следующих сценариях:

Поиск всех писем, связанных с конкретной сущностью CRM (контакт, компания, лид, сделка);
Фильтрация писем по направлению (входящие/исходящие) и статусу;
Поиск писем за определённый период времени;
Проверка наличия письма с определёнными параметрами по ID письма;
Поиск писем в смарт-процессах;
Проверка статуса прочтения исходящих писем;
Поиск необработанных входящих писем;
Аналитика и отчётность по письмам клиентов;
Автоматизация процессов на основе истории переписки;
Проверка условий выполнения писем для условной логики в бизнес-процессах.

Как работает активити (робот):
- Активити (робот) поддерживает два режима работы: проверка условий по ID письма и поиск писем в сущности по фильтрам;
- Если указан ID письма, активити (робот) проверяет соответствие письма указанным условиям (направление, статус, выполнено ли дело);
- Если ID письма не указан, активити (робот) ищет письма в указанной сущности по заданным фильтрам;
- Поддерживается поиск писем в стандартных сущностях (лид, сделка, контакт, компания) и смарт-процессах;
- Результаты возвращаются в виде массива ID писем и строки с ID через запятую;
- Поддерживается фильтрация по направлению письма (входящие/исходящие), статусу письма и статусу дела;
- Поддерживается фильтрация по дате создания письма (от и до);
- Активити (робот) работает через REST API Битрикс24 (crm.activity.list и crm.activity.get);
- Поддерживается обработка больших объёмов данных (более 50 писем) через batch-запросы.

Сценарий работы активити (робота) бизнес-процесса

Описание параметров активити (робота)

Название поля	Описание и примеры использования
ID письма	В данном поле указывается идентификатор письма для проверки его параметров. Это необязательный параметр, но если он указан, то другие параметры поиска (тип сущности, ID сущности и фильтры) не учитываются. Активити (робот) проверит соответствие письма указанным условиям (направление, статус письма, статус дела). Важно: Если указан ID письма, активити (робот) работает в режиме проверки условий. Параметры "Тип сущности", "ID сущности" и все фильтры игнорируются. Результат будет возвращён в параметре math_search_results (Y - соответствует условиям, N - не соответствует). Примеры: - {=Variable:LETTER_ID} - проверить письмо с ID из переменной предыдущего активити (робота); - 12345 - проверить письмо с ID 12345; - {=A1988_22222_92566_99999:search_results} - использовать ID письма из результата предыдущего поиска. Режим проверки условий: При указании ID письма активити (робот) проверяет соответствие письма указанным условиям: - Направление письма (обязательно указывается); - Статус письма (для входящих - статус дела, для исходящих - статус прочтения); - Статус дела (выполнено/не выполнено). Если все указанные условия выполнены, возвращается math_search_results = Y, иначе math_search_results = N.
Тип сущности	В данном поле указывается тип сущности CRM, в которой будет осуществлён поиск писем. Это необязательный параметр, используется только если не указан "ID письма". Выбирается из выпадающего списка. Варианты выбора: - LEAD - Лид; - DEAL - Сделка; - CONTACT - Контакт; - COMPANY - Компания; - QUOTE - Предложение; - SMART_INVOICE - Счёт (новый); - ORDER - Заказ; - СМАРТ: [название смарт-процесса] - для поиска писем в смарт-процессах (список формируется автоматически на основе настроек вашего портала). Примеры: - CONTACT - искать письма в контактах; - DEAL - искать письма в сделках; - LEAD - искать письма в лидах. Когда использовать: - Для поиска всех писем конкретной сущности; - Для фильтрации писем по типу сущности перед применением других фильтров.
ID сущности	В данном поле указывается идентификатор сущности CRM, в которой будет осуществлён поиск писем. Это необязательный параметр, используется только если указан "Тип сущности" и не указан "ID письма". Примеры: - {=Document:ID} - искать письма в текущей сущности из документа (контакт, компания, лид, сделка); - 123 - искать письма в сущности с ID 123; - {=Variable:CONTACT_ID} - использовать ID из переменной предыдущего активити (робота); - {=A1988_22222_92566_99999:search_results} - использовать ID из результата поиска (первый элемент массива); - {=Iterator:Value} - использовать ID для каждого элемента в итераторе. Когда использовать: - Для поиска всех писем конкретной сущности; - Для фильтрации писем по сущности перед применением других фильтров.
Направление письма	В данном поле указывается направление искомого письма: входящее или исходящее. Это обязательный параметр при поиске писем (если не указан ID письма). Варианты выбора: - Входящее (1) - письмо получено от клиента или партнёра; - Исходящее (2) - письмо отправлено клиенту или партнёру. Примеры использования: - Входящее (1) - найти только входящие письма; - Исходящее (2) - найти только исходящие письма. Особенности работы: - Для входящих писем проверяется статус дела (STATUS); - Для исходящих писем проверяется статус прочтения (READ_CONFIRMED в SETTINGS).
Статус письма	В данном поле указывается статус письма для фильтрации. Это необязательный параметр, используется как дополнительный фильтр при поиске писем или для проверки условий при указании ID письма. Варианты выбора: - Прочитано (1) - для исходящих писем: письмо прочитано получателем; - Не прочитано (2) - для исходящих писем: письмо не прочитано получателем; - Для входящих писем: статус дела (значение из поля STATUS). Примеры использования: - Прочитано (1) - найти только прочитанные исходящие письма; - Не прочитано (2) - найти только непрочитанные исходящие письма; - При указании ID письма - проверить, соответствует ли статус письма указанному значению. Особенности работы: - Для исходящих писем проверяется наличие ключа READ_CONFIRMED в SETTINGS; - Для входящих писем проверяется значение поля STATUS.
Статус дела	В данном поле указывается статус дела (выполнено или не выполнено) для фильтрации писем. Это необязательный параметр, используется как дополнительный фильтр при поиске писем или для проверки условий при указании ID письма. Варианты выбора: - Не выполнено (N) - дело не выполнено; - Выполнено (Y) - дело выполнено. Примеры использования: - Не выполнено (N) - найти только невыполненные письма; - Выполнено (Y) - найти только выполненные письма; - При указании ID письма - проверить, соответствует ли статус дела указанному значению. Когда использовать: - Для фильтрации необработанных писем; - Для поиска уже обработанных писем; - Для проверки статуса конкретного письма.
Дата создания от	В данном поле можно указать дату и время, начиная с которой будет осуществлён поиск писем. Это необязательный параметр, используется как дополнительный фильтр при поиске писем. Примеры: - {=System:NowLocal} - искать письма с текущей даты и времени; - ={{=dateadd({=System:Now}, "-7d")}} - искать письма за последние 7 дней; - ={{=dateadd({=System:Now}, "-1m")}} - искать письма за последний месяц; - 01.01.2025 00:00:00 - искать письма с указанной даты; - {=Variable:START_DATE} - использовать дату из переменной предыдущего активити (робота). Когда использовать: - Для поиска писем за определённый период; - Для анализа писем за последние дни/месяцы; - Для фильтрации писем по дате начала.
Дата создания до	В данном поле можно указать дату и время, до которой будет осуществлён поиск писем. Это необязательный параметр, используется как дополнительный фильтр при поиске писем. Примеры: - {=System:NowLocal} - искать письма до текущей даты и времени; - ={{=dateadd({=System:Now}, "1d")}} - искать письма до завтрашнего дня; - 31.12.2025 23:59:59 - искать письма до указанной даты; - {=Variable:END_DATE} - использовать дату из переменной предыдущего активити (робота). Когда использовать: - Для поиска писем за определённый период (в паре с параметром "Дата создания от"); - Для анализа писем до определённой даты; - Для фильтрации писем по дате окончания периода поиска.
Делать отладочные сообщения в журнал БП	Варианты: да/нет. Позволяет выбрать, нужно ли создавать отладочные сообщения в журнал БП или нет. Это поле нужно использовать только по необходимости из-за большого расхода запросов и уменьшенной скорости срабатывания активити (робота).
Запускать от имени	Данное поле необходимо для того, чтобы установить сотрудника, с правами которого выполнять действие данного активити (робота). Если у сотрудника не будет прав на выполнение действия, то активити (робот) не сработает. Рекомендуем выбирать всегда сотрудника с правами администратора системы.
Устанавливать текст статуса	Данное поле позволяет включать возможность установки статуса бизнес-процесса. Это необходимо для того, чтобы во время работы активити (робота) информировать пользователя в истории о том, что бизнес-процесс остановился на конкретном шаге. Это особенно важно в момент отладки и выяснения причин неполадок в работе механизма.
Текст статуса	В данном поле указывается текстовый вариант статуса, который Вы можете изменять. Используется только при включённом параметре "Устанавливать текст статуса".
Ожидать ответа	Данное поле Вами не управляется. Оно необходимо для того, чтобы определить, нужно ли ожидать реакции от нашего активити (робота) после запуска.
Период ожидания. Время ожидания ответа от приложения	Указывается в секундах, минутах, часах, днях, но не менее 5 минут и желательно не более 1 часа. Это поле нужно для аварийного завершения активити (робота), и если ответ не получен в течении того количества времени, то активити (робот) завершается.

Примеры использования активити (робота)

Описание примера	Решение
Проверка соответствия письма условиям по ID	Параметры: ID письма - {=Variable:LETTER_ID}, Направление письма - 2 (Исходящее), Статус письма - 1 (Прочитано), Статус дела - Y (Выполнено). Активити (робот) проверит, соответствует ли письмо указанным условиям. Результат будет возвращён в параметре math_search_results (Y или N).
Поиск всех входящих писем контакта	Параметры: Тип сущности - CONTACT, ID сущности - {=Document:ID}, Направление письма - 1 (Входящее), Статус письма - не указывается, Статус дела - не указывается, Дата создания от - не указывается, Дата создания до - не указывается. Активити (робот) найдёт все входящие письма контакта.
Поиск непрочитанных исходящих писем	Параметры: Тип сущности - CONTACT, ID сущности - {=Document:ID}, Направление письма - 2 (Исходящее), Статус письма - 2 (Не прочитано), Статус дела - не указывается, Дата создания от - не указывается, Дата создания до - не указывается. Активити (робот) найдёт все непрочитанные исходящие письма контакта.
Поиск необработанных входящих писем	Параметры: Тип сущности - DEAL, ID сущности - {=Document:ID}, Направление письма - 1 (Входящее), Статус письма - не указывается, Статус дела - N (Не выполнено), Дата создания от - не указывается, Дата создания до - не указывается. Активити (робот) найдёт все необработанные входящие письма сделки.
Поиск писем за последний месяц	Параметры: Тип сущности - CONTACT, ID сущности - {=Document:ID}, Направление письма - 2 (Исходящее), Статус письма - не указывается, Статус дела - не указывается, Дата создания от - ={{=dateadd({=System:Now}, "-1m")}}, Дата создания до - {=System:NowLocal}. Активити (робот) найдёт все исходящие письма контакта за последний месяц.
Поиск писем в смарт-процессе	Параметры: Тип сущности - СМАРТ: Заявки, ID сущности - {=Document:ID}, Направление письма - 1 (Входящее), Статус письма - не указывается, Статус дела - не указывается, Дата создания от - не указывается, Дата создания до - не указывается. Активити (робот) найдёт все входящие письма элемента смарт-процесса.
Поиск прочитанных исходящих писем за рабочий день	Параметры: Тип сущности - CONTACT, ID сущности - {=Document:ID}, Направление письма - 2 (Исходящее), Статус письма - 1 (Прочитано), Статус дела - не указывается, Дата создания от - ={{=date('d.m.Y 09:00:00', {=System:Now})}}, Дата создания до - ={{=date('d.m.Y 18:00:00', {=System:Now})}}. Активити (робот) найдёт все прочитанные исходящие письма контакта за текущий рабочий день.
Проверка статуса конкретного письма	Параметры: ID письма - {=Variable:LETTER_ID}, Направление письма - 1 (Входящее), Статус письма - не указывается, Статус дела - Y (Выполнено). Активити (робот) проверит, выполнено ли входящее письмо. Результат будет возвращён в параметре math_search_results.
Поиск писем через итератор	Параметры: Тип сущности - CONTACT, ID сущности - {=Iterator:Value}, Направление письма - 2 (Исходящее), Статус письма - не указывается, Статус дела - не указывается, Дата создания от - не указывается, Дата создания до - не указывается. Для каждого контакта из итератора активити (робот) найдёт все исходящие письма.
Поиск писем за определённый период с фильтрацией	Параметры: Тип сущности - DEAL, ID сущности - {=Document:ID}, Направление письма - 1 (Входящее), Статус письма - не указывается, Статус дела - N (Не выполнено), Дата создания от - ={{=dateadd({=System:Now}, "-30d")}}, Дата создания до - {=System:NowLocal}. Активити (робот) найдёт все необработанные входящие письма сделки за последние 30 дней.

Сценарий работы робота

Возвращаемые параметры данного активити (робота):
- Результат поиска (массив для итератора) (search_results_array) - массив чисел с ID найденных писем. Используется для итерации по результатам в бизнес-процессе.
- Результат поиска (строка) (search_results_string) - строка со всеми результатами поиска, разделёнными запятыми (например, "123,456,789"). Удобно для передачи в другие активити (роботы) или для отображения в отчётах.
- Первый результат поиска (search_result_first_string) - строка с первым результатом поиска (например, "123"). Полезно, когда нужно получить только первое письмо.
- Последний результат поиска (search_result_last_string) - строка с последним результатом поиска (например, "789"). Полезно для получения последнего письма из списка.
- Количество найденных элементов (count_search) - числовое значение, указывающее количество найденных писем. Используется для проверки наличия писем и для аналитики.
- Соответствует условиям (math_search_results) - строка, указывающая результат поиска или проверки условий. Возможные значения: Y (найдены письма или условия выполнены) или N (письма не найдены или условия не выполнены). Используется в условиях для проверки успешности поиска или соответствия условий.
- Логи ошибок (s_error_logs) - строка с описанием ошибки, если поиск завершился неудачно. Обычно пустая строка при успешном выполнении.

Особенности возвращаемых параметров:
- При указании ID письма: возвращается только параметр math_search_results (Y или N), другие параметры не заполняются;
- При поиске писем: возвращаются все параметры, включая массивы ID писем;
- Если найдено одно письмо: search_results_array содержит одно значение;
- Если найдено несколько писем: search_results_array содержит массив ID писем.

Важно о возвращаемых параметрах: Если вы хотите использовать результат работы активити (робота) в другом активити (роботе), в котором параметр - простое число, то несколько чисел, разделённых запятыми, работать не будут, так как параметр ждёт только одно число. Если параметр простой - строка, то туда не нужно вставлять результат работы в виде массива для итератора, так как данный параметр предназначен для полей с типом заполнения "множественное".

Важно! Ограничения и рекомендации:

Два режима работы:
Активити (робот) поддерживает два режима работы:
- Режим 1: Проверка условий по ID письма (если указан ID письма) - проверяет соответствие письма указанным условиям (направление, статус письма, статус дела);
- Режим 2: Поиск писем в сущности (если не указан ID письма) - ищет письма по заданным фильтрам в указанной сущности.

Обязательные параметры:
Для успешного поиска писем обязательно должны быть указаны параметры "Тип сущности", "ID сущности" и "Направление письма" (если не указан ID письма). Если указан ID письма, обязательно указывается "Направление письма" для проверки условий.

Проверка условий при указании ID письма:
При указании ID письма активити (робот) проверяет соответствие письма указанным условиям:
- Направление письма (обязательно) - проверяется точное совпадение;
- Статус письма (если указан) - для входящих проверяется STATUS, для исходящих проверяется READ_CONFIRMED в SETTINGS;
- Статус дела (если указан) - проверяется значение COMPLETED (Y или N).
Если все указанные условия выполнены, возвращается math_search_results = Y, иначе math_search_results = N.

Фильтрация при поиске писем:
При поиске писем (без указания ID письма) все указанные фильтры работают как условия поиска:
- Направление письма работает как точное совпадение;
- Статус письма фильтрует результаты по статусу;
- Статус дела фильтрует результаты по статусу выполнения;
- Даты работают как диапазон "от и до".

Работа со смарт-процессами:
Активити (робот) автоматически определяет смарт-процессы, доступные на вашем портале, и добавляет их в список типов сущностей. Список формируется автоматически на основе настроек портала. Для смарт-процессов используется формат TYPE_ID:OWNER_TYPE_ID (например, 4:135).

Работа с большими объёмами данных:
Активити (робот) автоматически обрабатывает случаи, когда результатов больше 50 писем, используя специальную структуру данных (many50). Все письма будут корректно обработаны и возвращены в результатах.

Права доступа:
Убедитесь, что пользователь, указанный в поле "Запускать от имени", имеет права на просмотр писем в CRM. Рекомендуется использовать пользователя с правами администратора системы.

Обработка результатов:
Если письма не найдены, параметр math_search_results будет равен N, а count_search будет равен 0. Всегда проверяйте значение параметра math_search_results перед использованием результатов в дальнейших шагах бизнес-процесса.

Ваша корзина пуста

Поиск писем в сущности