Запуск автоматизации

Запускайте автоматизацию по событию плагина и связывайте внешний объект с перепиской.

Сначала создайте событие плагина, которое разрешает запуск автоматизации.

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, не выполняя новый поиск. Поэтому сначала подготовьте связь, а затем отправляйте событие; не используйте повтор как способ дождаться появления диалога.

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