Выбрать курс
- Приложение для Битрикс24 "Лаборатория роботов"
- Приложение для Битрикс24 "Сквозная аналитика 2.0"
- Приложение для Битрикс24 "Уничтожитель дубликатов"
- Приложение для Битрикс24 "Межпортальные задачи"
- Приложение для Битрикс24 "Немой чат-бот"
- Приложение для Битрикс24 "Доходы и расходы CRM"
- Приложение для Битрикс24 "Продуктивный Jivosite"
119
/
330
Поиск Контакта (v.2)
Активити (робот) "Поиск контактов v2" предназначено для использования в роботах и бизнес-процессах и может быть полезно в следующих сценариях:
- Поиск контактов по ФИО, должности, адресу и другим полям;
- Поиск контактов по телефону или email с использованием механизма поиска дубликатов;
- Фильтрация контактов для создания отчётов и аналитики;
- Автоматический поиск связанных контактов при работе со сделками и лидами;
- Поиск дубликатов контактов для очистки базы данных;
- Поиск контактов по UTM-меткам для анализа эффективности маркетинга;
- Поиск контактов по дате создания или изменения для контроля актуальности данных;
- Поиск контактов по пользовательским полям для сложной фильтрации;
- Массовые операции над группой контактов (изменение полей, назначение ответственного);
- Интеграция с внешними системами через поиск по внешним идентификаторам.
Как работает активити (робот):
- Активити (робот) автоматически получает список всех доступных полей контакта из CRM вашего портала через REST API (crm.contact.fields);
- Для каждого поля создаётся параметр поиска, который можно заполнить для фильтрации;
- Для полей PHONE и EMAIL используется специальный механизм поиска дубликатов (crm.duplicate.findbycomm);
- Можно комбинировать несколько полей для более точного поиска;
- Поиск выполняется по принципу "И" (AND) - все указанные условия должны выполняться одновременно;
- Поддерживается обработка больших объёмов данных (более 50 контактов) через batch-запросы;
- Результаты возвращаются в виде массива ID контактов, строки с ID через запятую, первого и последнего ID, количества найденных контактов.
- Активити (робот) автоматически получает список всех доступных полей контакта из CRM вашего портала через REST API (crm.contact.fields);
- Для каждого поля создаётся параметр поиска, который можно заполнить для фильтрации;
- Для полей PHONE и EMAIL используется специальный механизм поиска дубликатов (crm.duplicate.findbycomm);
- Можно комбинировать несколько полей для более точного поиска;
- Поиск выполняется по принципу "И" (AND) - все указанные условия должны выполняться одновременно;
- Поддерживается обработка больших объёмов данных (более 50 контактов) через batch-запросы;
- Результаты возвращаются в виде массива ID контактов, строки с ID через запятую, первого и последнего ID, количества найденных контактов.
Сценарий работы активити (робота) бизнес-процесса
Описание параметров активити (робота)
| Название поля | Описание и примеры использования |
|---|---|
| Сообщение об ошибке | В данном поле указывается, будет ли выводиться сообщение об ошибке в журнал БП или нет. Варианты: да/нет. |
| ID | В данном поле указывается числовой идентификатор искомого контакта. Примеры: - ={123} - найти контакт с ID равным 123; - ={!123} - найти все контакты, кроме контакта с ID 123; - {=Document:CONTACT_ID} - использовать ID контакта из текущего документа. |
| Имя | В данном поле указывается имя искомого контакта. Поддерживает поиск по частичному совпадению. Примеры: - ={%Иван} - найти контакты, имя которых содержит "Иван"; - ={Иван} - найти контакты с точным именем "Иван"; - ={!%Тест} - найти контакты, имя которых не содержит "Тест". |
| Отчество | В данном поле указывается отчество искомого контакта. Поддерживает поиск по частичному совпадению. Примеры: - ={%Иванович} - найти контакты с отчеством, содержащим "Иванович"; - ={Петрович} - найти контакты с точным отчеством "Петрович". |
| Фамилия | В данном поле указывается фамилия искомого контакта. Поддерживает поиск по частичному совпадению. Примеры: - ={%Петров} - найти контакты с фамилией, содержащей "Петров"; - ={Иванов} - найти контакты с точной фамилией "Иванов"; - {=Document:LAST_NAME} - использовать фамилию из текущего документа. |
| Описание | В данном поле указывается текст описания искомого контакта. Поддерживает поиск по частичному совпадению. Примеры: - ={%VIP} - найти контакты, описание которых содержит "VIP"; - ={!%тест} - найти контакты, описание которых не содержит "тест". |
| Должность | В данном поле указывается должность искомого контакта. Примеры: - ={%директор} - найти контакты с должностью, содержащей "директор"; - ={Менеджер} - найти контакты с точной должностью "Менеджер". |
| Адрес | В данном поле указывается фактический адрес контакта (устаревшее поле, сейчас используются реквизиты). Примеры: - ={%Москва} - найти контакты с адресом, содержащим "Москва". |
| Адрес (стр. 2) | В данном поле указывается адрес квартиры или офиса контакта (устаревшее поле, сейчас используются реквизиты). |
| Город | В данном поле указывается город расположения контакта (устаревшее поле, сейчас используются реквизиты). Примеры: - ={Санкт-Петербург} - найти контакты из Санкт-Петербурга. |
| Почтовый индекс | В данном поле указывается почтовый индекс контакта (устаревшее поле, сейчас используются реквизиты). |
| Район | В данном поле указывается район контакта. |
| Область | В данном поле указывается область контакта. |
| Страна | В данном поле указывается страна контакта. Примеры: - ={Россия} - найти контакты из России. |
| Код страны | В данном поле указывается код страны контакта. Примеры: - ={RU} - найти контакты с кодом страны RU. |
| Комментарий | В данном поле указывается текст комментария к контакту. Поддерживает поиск по частичному совпадению. Примеры: - ={%важно} - найти контакты, комментарий которых содержит "важно". |
| Дата создания | В данном поле указывается дата создания контакта. Поддерживает поиск по точной дате и диапазонам дат. Примеры: - ={=>01.01.2025 00:00:00} - найти контакты, созданные после 1 января 2025 года; - ={{01.01.2025 00:00:00}}##{{31.12.2025 23:59:59}} - найти контакты, созданные в 2025 году. |
| Дата изменения | В данном поле указывается дата последнего изменения контакта. Примеры: - ={=>01.03.2025 00:00:00} - найти контакты, изменённые после 1 марта 2025 года. |
| Внешний источник | В данном поле указывается идентификатор внешней информационной базы. Назначение поля может меняться конечным разработчиком. |
| Идентификатор элемента внешнего источника | В данном поле указывается внешний ключ, используемый для операций обмена. Идентификатор объекта внешней информационной базы. |
| Версия оригинала | В данном поле указывается версия внешнего ключа, используемого для операций обмена. |
| Рекламная система (UTM_SOURCE) | В данном поле указывается UTM SOURCE из UTM-метки. Примеры: - ={%google} - найти контакты из рекламной системы Google; - ={%yandex} - найти контакты из рекламной системы Yandex. |
| Тип трафика (UTM_MEDIUM) | В данном поле указывается UTM MEDIUM из UTM-метки. Примеры: - ={%cpc} - найти контакты с типом трафика "cost per click"; - ={%organic} - найти контакты с органическим трафиком. |
| Обозначение рекламной кампании (UTM_CAMPAIGN) | В данном поле указывается UTM CAMPAIGN из UTM-метки. Примеры: - ={%летняя} - найти контакты из кампании "летняя распродажа". |
| Содержание кампании (UTM_CONTENT) | В данном поле указывается UTM CONTENT из UTM-метки. |
| Условие поиска кампании (UTM_TERM) | В данном поле указывается UTM TERM из UTM-метки (обычно ключевое слово). |
| Телефон | В данном поле указывается номер телефона для поиска контакта. Поиск осуществляется через механизм поиска дубликатов (crm.duplicate.findbycomm). Примеры: - +79001234567 - найти контакт с указанным телефоном; - {=Document:PHONE} - использовать телефон из текущего документа. |
| В данном поле указывается email для поиска контакта. Поиск осуществляется через механизм поиска дубликатов (crm.duplicate.findbycomm). Примеры: - test@example.com - найти контакт с указанным email; - {=Document:EMAIL} - использовать email из текущего документа. |
|
| Делать отладочные сообщения в журнал БП | Варианты: да/нет. Позволяет выбрать, нужно ли создавать отладочные сообщения в журнал БП или нет. Это поле нужно использовать только по необходимости из-за большого расхода запросов и уменьшенной скорости срабатывания активити (робота). |
| Запускать от имени | Данное поле необходимо для того, чтобы установить сотрудника, с правами которого выполнять действие данного активити (робота). Если у сотрудника не будет прав на выполнение действия, то активити (робот) не сработает. Рекомендуем выбирать всегда сотрудника с правами администратора системы. |
| Устанавливать текст статуса | Данное поле позволяет включать возможность установки статуса бизнес-процесса. Это необходимо для того, чтобы во время работы активити (робота) информировать пользователя в истории о том, что бизнес-процесс остановился на конкретном шаге. Это особенно важно в момент отладки и выяснения причин неполадок в работе механизма. |
| Текст статуса | В данном поле указывается текстовый вариант статуса, который Вы можете изменять. |
| Ожидать ответа | Данное поле Вами не управляется. Оно необходимо для того, чтобы определить, нужно ли ожидать реакции от нашего активити (робота) после запуска. |
| Период ожидания (Время ожидания ответа от приложения) | Указывается в секундах, минутах, часах, днях, но не менее 5 минут и желательно не более 1 часа. Это поле нужно для аварийного завершения активити (робота), и если ответ не получен в течении того количества времени, то активити (робот) завершается. |
Операторы сравнения для поиска
Данные символы ставятся перед содержимым ячейки:
- ={%ваше значение} - содержит (можно искать буквы и цифры в выбранной вами строке).
Пример заполнения: ={%груша}, вернет все ID сущностей, в которых, в выбранном вами поле, содержится слово "груша".
- ={!%ваше значение} - не содержит.
Пример заполнения: ={!%123}, это значит, что значение в выбранном поле не содержит 123.
- ={ваше значение} - равно.
Пример заполнения: ={123}, это значит, что значение в выбранном поле равно 123 (только для поля тип "строка" и "число"). Если в поле используется текст, то этот текст должен совпадать символ в символ.
- ={!ваше значение} - не равно.
Пример заполнения: ={!123}, это значит, что значение в выбранном поле не равно 123.
- ={>ваше значение} - больше.
Пример заполнения: ={>123}, это значит, что значение в выбранном поле больше 123 (только для поля тип "число").
- ={<ваше значение} - меньше.
Пример заполнения: ={<123}, это значит, что значение в выбранном поле меньше 123 (только для поля тип "число").
- ={=>} - больше или равно.
Пример заполнения: ={=>123}, это значит, что значение в поле больше или равно 123 (только для поля тип "число").
- ={=<} - меньше или равно.
Пример заполнения: ={=<123}, это значит, что значение в поле меньше или равно 123 (только для поля тип "число").
Для полей типа "дата" и "дата/время":
- Если поле не является строкой, то содержимое ячейки должно заполняться так: ={=>14.03.2020 15:10}, в фигурных скобках указывается необходимый символ.
- В случае с переменной, содержимое ячейки должно заполняться так: ={=>{=Variable:search_date}}.
- При необходимости поиска диапазона "от и до" содержимое ячейки должно заполняться так: ={{01.03.2015 14:55:22}}##{{07.05.2015 14:55:22}}
- ={%ваше значение} - содержит (можно искать буквы и цифры в выбранной вами строке).
Пример заполнения: ={%груша}, вернет все ID сущностей, в которых, в выбранном вами поле, содержится слово "груша".
- ={!%ваше значение} - не содержит.
Пример заполнения: ={!%123}, это значит, что значение в выбранном поле не содержит 123.
- ={ваше значение} - равно.
Пример заполнения: ={123}, это значит, что значение в выбранном поле равно 123 (только для поля тип "строка" и "число"). Если в поле используется текст, то этот текст должен совпадать символ в символ.
- ={!ваше значение} - не равно.
Пример заполнения: ={!123}, это значит, что значение в выбранном поле не равно 123.
- ={>ваше значение} - больше.
Пример заполнения: ={>123}, это значит, что значение в выбранном поле больше 123 (только для поля тип "число").
- ={<ваше значение} - меньше.
Пример заполнения: ={<123}, это значит, что значение в выбранном поле меньше 123 (только для поля тип "число").
- ={=>} - больше или равно.
Пример заполнения: ={=>123}, это значит, что значение в поле больше или равно 123 (только для поля тип "число").
- ={=<} - меньше или равно.
Пример заполнения: ={=<123}, это значит, что значение в поле меньше или равно 123 (только для поля тип "число").
Для полей типа "дата" и "дата/время":
- Если поле не является строкой, то содержимое ячейки должно заполняться так: ={=>14.03.2020 15:10}, в фигурных скобках указывается необходимый символ.
- В случае с переменной, содержимое ячейки должно заполняться так: ={=>{=Variable:search_date}}.
- При необходимости поиска диапазона "от и до" содержимое ячейки должно заполняться так: ={{01.03.2015 14:55:22}}##{{07.05.2015 14:55:22}}
Примеры использования активити (робота)
| Описание примера | Решение |
|---|---|
| Поиск контакта по телефону +79001234567 | Параметры: Телефон - +79001234567. Активити (робот) найдёт контакт с указанным номером телефона через механизм поиска дубликатов. Результат будет возвращён в параметре search_results_array. |
| Поиск контакта по email из текущей сделки | Параметры: E-mail - {=Document:EMAIL}. Активити (робот) найдёт контакт с email из текущего документа. |
| Поиск контактов с фамилией, содержащей "Иванов" | Параметры: Фамилия - ={%Иванов}. Активити (робот) найдёт все контакты, фамилия которых содержит "Иванов" (Иванов, Иванова, Ивановский и т.д.). |
| Поиск контактов из Москвы с должностью директор | Параметры: Город - ={Москва}, Должность - ={%директор}. Активити (робот) найдёт все контакты из Москвы, должность которых содержит слово "директор". |
| Поиск контактов, созданных за последний месяц | Параметры: Дата создания - ={=>{=dateadd({=System:Now}, "-1m")}}. Активити (робот) найдёт все контакты, созданные за последний месяц. |
| Поиск контактов из рекламной кампании Google | Параметры: Рекламная система (UTM_SOURCE) - ={%google}. Активити (робот) найдёт все контакты, пришедшие из рекламной системы Google. |
| Поиск контактов по точному ФИО: Иванов Иван Иванович | Параметры: Фамилия - ={Иванов}, Имя - ={Иван}, Отчество - ={Иванович}. Активити (робот) найдёт контакт с точным совпадением ФИО. |
| Поиск контактов, кроме тестовых | Параметры: Имя - ={!%тест}, Описание - ={!%тест}. Активити (робот) найдёт все контакты, имя и описание которых не содержат слово "тест". |
| Поиск контактов по внешнему идентификатору из 1С | Параметры: Идентификатор элемента внешнего источника - ={1C_12345}. Активити (робот) найдёт контакт с указанным внешним идентификатором для синхронизации с 1С. |
| Поиск контактов, изменённых в определённый период | Параметры: Дата изменения - ={{01.01.2025 00:00:00}}##{{31.01.2025 23:59:59}}. Активити (робот) найдёт все контакты, изменённые в январе 2025 года. |
Сценарий работы робота
Возвращаемые параметры данного активити (робота):
- Результат поиска (массив для итератора) (search_results_array) - массив чисел с ID найденных контактов (например, [123, 456, 789]). Используется для итерации по результатам в бизнес-процессе.
- Результат поиска (строка) (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) - строка с описанием ошибки или сообщением об успешном выполнении. При успешном выполнении содержит сообщение "contact_search_v2_error_2: [количество найденных контактов]".
- Результат поиска (массив для итератора) (search_results_array) - массив чисел с ID найденных контактов (например, [123, 456, 789]). Используется для итерации по результатам в бизнес-процессе.
- Результат поиска (строка) (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) - строка с описанием ошибки или сообщением об успешном выполнении. При успешном выполнении содержит сообщение "contact_search_v2_error_2: [количество найденных контактов]".
Важно о возвращаемых параметрах: Если контакты не найдены, параметр math_search_results будет равен N, а count_search будет равен 0. Всегда проверяйте значение параметра math_search_results перед использованием результатов в дальнейших шагах бизнес-процесса.
Важно! Ограничения и рекомендации:
Поиск по телефону и email:
При поиске по полям PHONE или EMAIL используется специальный механизм поиска дубликатов (crm.duplicate.findbycomm), который работает более эффективно для этих типов полей. Телефоны и email ищутся отдельно от других полей.
Динамическая поддержка полей:
Активити (робот) автоматически получает список всех доступных полей контакта из вашего портала, включая пользовательские поля. Это означает, что вы можете искать по любым полям, доступным в вашей CRM.
Обработка больших объёмов данных:
Активити (робот) автоматически обрабатывает случаи, когда результатов больше 50 контактов, используя batch-запросы. Все контакты будут корректно обработаны и возвращены в результатах.
Комбинирование условий:
При указании нескольких полей для поиска, все условия объединяются по принципу "И" (AND). Это означает, что будут найдены только те контакты, которые соответствуют всем указанным условиям одновременно.
Права доступа:
Убедитесь, что пользователь, указанный в поле "Запускать от имени", имеет права на просмотр контактов в CRM. Рекомендуется использовать пользователя с правами администратора системы.
Устаревшие поля адреса:
Поля Адрес, Город, Почтовый индекс и другие адресные поля являются устаревшими. В современных версиях Битрикс24 для хранения адресов рекомендуется использовать реквизиты.
Поиск по телефону и email:
При поиске по полям PHONE или EMAIL используется специальный механизм поиска дубликатов (crm.duplicate.findbycomm), который работает более эффективно для этих типов полей. Телефоны и email ищутся отдельно от других полей.
Динамическая поддержка полей:
Активити (робот) автоматически получает список всех доступных полей контакта из вашего портала, включая пользовательские поля. Это означает, что вы можете искать по любым полям, доступным в вашей CRM.
Обработка больших объёмов данных:
Активити (робот) автоматически обрабатывает случаи, когда результатов больше 50 контактов, используя batch-запросы. Все контакты будут корректно обработаны и возвращены в результатах.
Комбинирование условий:
При указании нескольких полей для поиска, все условия объединяются по принципу "И" (AND). Это означает, что будут найдены только те контакты, которые соответствуют всем указанным условиям одновременно.
Права доступа:
Убедитесь, что пользователь, указанный в поле "Запускать от имени", имеет права на просмотр контактов в CRM. Рекомендуется использовать пользователя с правами администратора системы.
Устаревшие поля адреса:
Поля Адрес, Город, Почтовый индекс и другие адресные поля являются устаревшими. В современных версиях Битрикс24 для хранения адресов рекомендуется использовать реквизиты.