Триггеры

Триггеры — это стартовые блоки сценария. Триггер определяет, какое событие и при каких условиях запустит ваш процесс. Когда происходит это событие, триггер активируется и передает управление следующему блоку.

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

На платформе доступны следующие типы триггеров:

• Вебхук — запускается по HTTP-запросу из внешней системы.
• Планировщик — активируется по заданному расписанию.
• Сообщение — реагирует на сообщения и события в текстовых каналах.
• IMAP Email — запускается при получении писем.

предупреждение

• Триггеры Вебхук, Планировщик и IMAP Email запускают процесс сразу для всех пользователей и каналов.

Как добавить триггер на холст

1. Перейдите в проект и на левой панели нажмите , чтобы открыть конструктор.
2. В верхнем левом углу холста нажмите  — откроется список блоков.
3. Раскройте список Триггеры и перетащите нужный блок на холст.
4. Соедините триггер со следующим блоком в сценарии.

Триггер «Вебхук»

Этот триггер запускает процесс по HTTP-запросу из внешней системы, например из CRM или ERP.

Особенности:

• Для каждого блока Вебхук на холсте автоматически генерируется уникальный URL.
• Вебхук не требует дополнительной аутентификации. Любой, у кого есть ссылка, может запустить связанный с ней процесс.
• Вебхук запускает процесс сразу для всех пользователей во всех каналах.
• Вебхук не передает в процесс никакую дополнительную информацию.

Настройка

Нажмите на блок Вебхук и скопируйте уникальный URL.

Чтобы запустить процесс, внешняя система должна отправить GET-запрос на этот URL. При успешном вызове сервер вернет 200 OK, и сценарий будет запущен.

подсказка

Чтобы протестировать вебхук, скопируйте его URL и откройте в браузере.

Триггер «Планировщик»

Этот триггер запускает процесс по заданному расписанию. Он идеально подходит для автоматизации рутинных задач, таких как формирование отчетов или рассылка сообщений.

Особенности:

• Планировщик запускает процесс сразу для всех пользователей во всех каналах.
• Планировщик не передает в процесс никакую дополнительную информацию.

Настройка

1. Нажмите на блок Планировщик, чтобы открыть настройки.

2. Выберите вариант расписания:

   • Простое — для быстрой настройки с помощью готовых интервалов. Укажите дату и время первого запуска, выберите периодичность и условие окончания.

     предупреждение

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

   • Cron-выражение — для более гибкой настройки. Укажите Cron-выражение в формате Quartz и условие окончания. Например, 0 30 9 ? * MON — каждый понедельник в 9:30.

   После настройки расписания платформа отобразит информацию о ближайших запланированных запусках (не более 5).

3. Нажмите Запустить.

к сведению

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

Чтобы случайно не отправить сообщение во все каналы при редактировании триггера в уже опубликованном процессе, используйте для отладки блок Условие с функцией Context.isTestChannel(). Добавьте условие после планировщика, опубликуйте процесс, затем внесите изменения и протестируйте их в тестовом виджете.

Триггер «Сообщение»

Этот триггер срабатывает, когда в подключенный канал поступает сообщение, файл, геолокация, контакт или стикер, а также при открытии окна тестового виджета.

Каналы работают независимо друг от друга. Ответ будет доставлен в тот канал, откуда пришло исходное событие.

Настройка

В триггере Сообщение автоматически подключены все настроенные в проекте каналы. Добавить или редактировать каналы можно как в разделе Интеграции, так и в самом триггере — эти способы эквиваленты. Если в проекте не подключен ни один канал, триггер срабатывает только в тестовом виджете.

Использование

С агентом

Соедините триггер Сообщение с блоком Агент. Агент обработает сообщение пользователя в соответствии со своим промтом и другими настройками. Примеры смотрите в разделах Быстрый старт: Шаг 2 и Работа агента в процессе.

С функцией

Триггер Сообщение можно соединить с функцией. Для извлечения различных данных о сообщении используйте встроенные функции из раздела Context. Например, функция Context.getMessageContent() возвращает содержание сообщения, Context.getChannelType() — тип канала.

Рассмотрим тривиальный пример эхо-бота:

1. Добавьте на холст триггер Сообщение и функцию Reactions.sendText(), соедините их последовательно.
2. В настройках функции Reactions.sendText укажите значение {{"Вы сказали: " + Context.getMessageContent().text}}.

Такой бот на сообщение «Привет» ответит «Вы сказали: Привет».

Триггер «IMAP Email»

Этот триггер подключается к почтовому ящику по протоколу IMAP. Он отслеживает появление новых писем в указанной папке и запускает процесс при их получении.

Особенности:

• Передает в контекст полную информацию о письме: отправитель, получатели (to/cc/bcc), тема, содержимое (HTML и plain текст), вложения, заголовки, флаги, дата отправки. Эти данные доступны через функцию Context.getEmailContent().
• Обрабатывает письма последовательно (по одному за раз). Если писем много, обработка очереди может занять некоторое время.
• Срабатывает не мгновенно, а с периодичностью опроса почтового сервера (polling).
• Требует предварительной настройки подключения к IMAP-серверу в разделе Интеграции.

Настройка

Для работы триггера настройте IMAP-подключение к почтовому ящику.

Шаг 1. Настройте IMAP-подключение

Добавьте учетные данные:

1. В проекте перейдите в раздел Учетные данные. Подробнее о нем читайте в статье.
2. Добавьте новые учетные данные с типом IMAP. У некоторых почтовых сервисов могут быть особые требования к паролю, обратитесь за точной информацией к документации вашего сервиса.

Далее создайте интеграцию:

1. Перейдите в раздел Интеграции.
2. Создайте и настройте новую интеграцию с типом IMAP-сервер.

Шаг 2. Настройте блок «IMAP Email»

1. Нажмите на блок IMAP Email.

2. Выберите созданную интеграцию и задайте Имя почтового ящика (папка на сервере, которую нужно отслеживать, например, INBOX или ReadyForAI).

3. Настройте логику обработки писем:

   • Загружать только новые письма: если включено, триггер будет игнорировать письма, у которых уже стоит флаг «Прочитано». Это предотвращает повторную обработку старых писем при перезапуске сценария.
   • Помечать прочитанными: если включено, после успешного взятия письма в работу триггер установит на сервере для письма статус «Прочитано».
   Рекомендованная связка

   Включите обе опции. Это гарантирует, что каждое письмо будет обработано только один раз.

4. Настройте скачивание вложений, если они необходимы для сценария.

5. При необходимости настройте фильтр по дате (обрабатывать письма начиная с определенного числа).

6. Нажмите Запустить.

После публикации сценария триггер начнет периодически проверять указанную папку на наличие писем, удовлетворяющих условиям.

Рекомендации по использованию

Для стабильной работы и экономии ресурсов, в том числе токенов LLM при использовании AI-агентов, мы рекомендуем придерживаться следующего подхода:

Отбор писем в папку

В текущей версии триггера нет сложных фильтров по теме или отправителю. Хотя вы можете отфильтровать ненужные письма логикой внутри сценария (например, блоком Условие на основе Context.getEmailContent()), загрузка лишних писем на платформу неэффективна: это замедляет обработку и забивает очередь.

Кроме того, если для обработки писем используется AI-агент, он будет читать лишние письма и тратить токены. Предварительная фильтрация на уровне почтового сервера обеспечивает максимальную прозрачность: вы точно знаете, какие письма попадут в обработку.

Лучшая практика:

1. Создайте в почтовом ящике (Outlook, Gmail, Яндекс или другой) отдельную папку для интеграции (например, ReadyForAI).
2. Настройте на стороне почтового сервера автоматическое правило (Filter/Rule), которое перемещает нужные письма в эту папку.
3. В настройках триггера укажите именно эту папку.

Работа с группами рассылки

Если для интеграции используется адрес вроде support@company.com, уточните у системного администратора его тип:

• Полноценный почтовый ящик: можно подключаться по IMAP напрямую, используя логин и пароль.
• Группа рассылки (Alias/Distribution Group): у такого адреса нет собственного хранилища, письма пересылаются участникам группы. Подключить такую группу по IMAP может быть невозможно. В таком случае попросите администратора создать реальный служебный ящик, включить его в группу рассылки и подключите триггер к нему.

Использование данных письма

Для извлечения различных данных о письме используйте функцию Context.getEmailContent() из коллекции Context. Например, Context.getEmailContent().subject возвращает тему письма, Context.getEmailContent().from — адрес отправителя.

Рассмотрим пример сценария автоответа (или уведомления):

1. Добавьте на холст триггер IMAP Email.
2. Добавьте блок Reactions.sendText() и соедините их.
3. В настройках функции Reactions.sendText укажите значение: {{"Получено письмо от " + Context.getEmailContent().from + " с темой: " + Context.getEmailContent().subject}}

Теперь при получении письма от client@example.com с темой «Заказ № 123» система сгенерирует сообщение: «Получено письмо от client@example.com с темой: Заказ № 123».