События приложений

Как добавить событие

Событие сообщает Senler о том, что произошло в вашем приложении: например заказ оплачен или сделка закрыта. На него может отреагировать агент, а событие плагина может также начать автоматизацию. Пользователь проекта сам подключает нужную реакцию; создание события в приложении ещё не запускает обработку.

Объявление событий доступно приложениям типов «Интеграция на сайте» и «Плагин». В интерфейсе раздел пока называется «События для агентов».

1. Откройте форму

Откройте раздел «События для агентов» и нажмите «Добавить», чтобы открыть страницу нового события.

2. Назовите событие для пользователя

В блоке для пользователя заполните название и краткое описание на вкладке «Русский», затем английское название и описание на вкладке English. Пользователь увидит вариант на языке своего интерфейса.

3. Задайте системное имя

Укажите системное имя, которое приложение будет отправлять через API, например payment.paid.

В блоке «Где доступно событие» выберите хотя бы один вариант:

• «Реакция агента» — пользователь сможет добавить событие своему агенту;
• «Начало автоматизации» — для плагина событие появится среди источников запуска автоматизаций «Для диалогов».

Можно включить оба варианта. Отдельное описание для агента показывается только при включённой реакции агента.

Если агенту нужно иначе сформулировать полученный факт, включите отдельное техническое описание и заполните текст для агента.

4. Опишите передаваемые данные

Если вместе с событием передаются данные, в блоке «Данные события» нажмите «Добавить поле».

В каждой карточке поля задайте имя, выберите в поле типа подходящий вариант. На вкладках «Русский» и English заполните русское и английское описание, затем при необходимости включите обязательность. Удаление убирает ненужное поле. Если дополнительных данных нет, оставьте этот блок пустым.

5. Сохраните событие

Нажмите «Сохранить». «Отмена» возвращает к списку без изменений.

Как подключить событие агенту

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

Приложение передаёт событие вместе с конкретными dialog_id и agent_id. Senler AI запускает агента, только если он назначен на этот диалог и подписан на событие. Поэтому одно объявление события ещё ничего не запускает — сначала пользователь должен подключить его агенту.

Как начать автоматизацию

1. Разрешите запуск и подготовьте схему

Для плагина включите «Начало автоматизации». Пользователь устанавливает плагин в проект, добавляет событие в схему «Для диалогов», указывает переменную данных и публикует автоматизацию. Порядок показан в статье «Событие приложения».

Событие передаётся через POST /api/app-automation-events с проектным OAuth-токеном установки приложения и правом can_manage_agent_events. Это другой способ доставки, чем адресный вызов агента с dialog_id и agent_id.

2. Свяжите внешний объект с перепиской

Чтобы Senler понял, к какому диалогу относится оплата, сначала сохраните в нём внешний идентификатор заказа. Для этого приложение вызывает POST /api/app-automation-events/dialogs/:dialogId/variables/:name/add-unique-items, например с именем order_ids и телом:

{ "items": ["order-42"] }

Метод создаёт определение переменной диалога типа «Массив» со строковыми элементами, если его ещё нет, и добавляет только отсутствующие идентификаторы. Это поле проекта, не скрытая переменная приложения. Для нового имени дайте методу создать определение самому: уже существующее поле должно совпадать и по типу, и по схеме данных.

3. Передайте событие

В теле POST /api/app-automation-events передайте:

• external_event_id — уникальный ID факта во внешней системе; при повторной отправке того же факта используйте прежний ID и те же данные;
• type — объявленное системное имя события;
• occurred_at — необязательные дата и время события;
• data — объект по описанной схеме, включая обязательные поля; если полей нет, всё равно передайте "data": {};
• routing — правило выбора диалога.

ID external_event_id уникален в пределах установки приложения: используйте до 200 символов, начиная с латинской буквы или цифры; далее разрешены также ., _, : и -. Системное имя type начинается со строчной латинской буквы, состоит из строчных латинских букв и цифр с разделителями . или _ между частями и не превышает 64 символа. Если передаёте occurred_at, используйте дату и время ISO 8601.

Например, если у события payment.paid объявлено строковое поле order_id:

{
  "external_event_id": "payment:42",
  "type": "payment.paid",
  "data": { "order_id": "order-42" },
  "routing": {
    "dialog_variable_name": "order_ids",
    "dialog_variable_value": "order-42",
    "create_dialog_if_missing": false
  }
}

В routing обязательны dialog_variable_name, dialog_variable_value и create_dialog_if_missing. Senler сначала ищет точное строковое значение среди идентификаторов, сохранённых в указанной переменной диалога.

Событие направляется в один диалог, а не во все совпавшие. Сохраняйте один внешний идентификатор только в нужной переписке: метод add-unique-items предотвращает повторы внутри её массива, но не запрещает добавить тот же ID в другой диалог.

Для резервного поиска передайте вместе lead_variable_name и lead_variable_value: тогда используется последний активный личный диалог подходящего лида. Значение переменной лида может быть строкой, числом или логическим значением. Senler сохраняет внешний идентификатор в выбранном диалоге, чтобы следующие события находили его напрямую.

Если активной личной переписки нет, create_dialog_if_missing: true разрешает создать её для найденного доступного лида. Сам по себе этот флаг, без двух полей резервного поиска, не создаёт ни лида, ни диалог.

4. Проверьте результат

Проверьте status, а не только успешный HTTP-ответ:

• scheduled — событие принято к обработке. Это ещё не подтверждение завершения автоматизации; проверьте её процесс.
• ignored — подходящий диалог не найден, запуск не запланирован.
• duplicate: true — сервер уже видел этот ID. Для завершённой доставки возвращается прежний результат, повторного запуска нет.

Сохраняйте external_event_id вместе с исходным запросом. При повторе не меняйте type, data, routing или occurred_at: изменение любого из них с прежним ID приводит к ошибке 409 Conflict. Например, нельзя подставлять текущее время заново при каждой попытке доставки.

Результат ignored тоже сохраняется. Если после него добавить связь с диалогом и повторить тот же запрос, сервер снова вернёт ignored, не выполняя новый поиск. Поэтому сначала подготовьте связь, а затем отправляйте событие; не используйте повтор как способ дождаться появления диалога.

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

Изменение и удаление

На странице «События для агентов» можно нажать «Добавить» для нового события или выбрать существующее в списке. Через действие редактирования можно изменить названия, описание и схему данных. После изменения схемы убедитесь, что приложение отправляет данные в новом формате.

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