Шаги автоматизаций

В разделе «Шаги автоматизаций» вы создаёте шаги своего приложения. Например, для CRM можно добавить шаг «Создать сделку», а для сервиса рассылок — «Добавить подписчика».

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

Шаг 1 — Откройте список шагов

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

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

Шаг 2 — Заполните вкладку «Основное»

На странице создания шага заполните основные сведения:

1. Введите техническое имя, например create_deal. Оно должно быть уникальным внутри приложения, начинаться с латинской буквы и содержать не более 64 латинских букв, цифр, символов _ и -.
2. Укажите URL webhook, на который Senler отправит запрос при выполнении шага.
3. Заполните название и краткое описание на русском и английском. По ним пользователь поймёт, что делает шаг. Текст будет показан на языке проекта.
4. В блоке «Типы автоматизаций» оставьте хотя бы один тип:
   • «Для диалогов» — шаг доступен в автоматизациях «Для диалогов» и может получить контекст лида, диалога и канала;
   • «Фоновые» — шаг доступен в фоновых автоматизациях, где лида и диалога может не быть.
5. В блоке «Иконка шага» выберите готовый значок или загрузите PNG, JPEG либо WebP. В редакторе основным изображением узла останется иконка приложения, а значок шага появится в углу.

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

Шаг 3 — Выберите, как пользователь будет настраивать шаг

Теперь решите, что увидит пользователь, когда добавит шаг в автоматизацию. В блоке «Режим настройки шага» выберите один вариант.

Конструктор настроек

Выберите этот вариант, если шаг можно настроить обычными полями: строкой, числом, переключателем «Да / нет», датой, массивом, объектом или JSON. Поля вы добавите на вкладках «Параметры» и «Результат», а Senler соберёт из них готовую форму.

В этом режиме доступны «Один выход „Далее“» и «Фиксированные ветки». Вариант «Ветки после настройки» с конструктором не работает.

Встроенная страница в панели

Выберите её для собственной компактной формы. Интерфейс приложения появится прямо в боковой панели выбранного узла. В настройках приложения должен быть указан основной URL встроенной страницы; показывать главную страницу приложения в меню проекта необязательно.

Встроенная страница во всплывающем окне

Выберите её для объёмной формы. В боковой панели пользователь нажмёт «Открыть настройки шага», после чего интерфейс приложения откроется в большом окне. Для этого также достаточно настроенного основного URL встроенной страницы.

Входные параметры и результаты можно объявить и для встроенной страницы. В этом режиме Senler не рисует их рядом с iframe: встроенная форма получает описание полей, текущие значения и привязки результатов через Senler Bridge и сама показывает нужный интерфейс. Вариант «Ветки после настройки» доступен только со встроенной страницей.

Шаг 4 — Опишите входные параметры и результат

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

На вкладке «Параметры» добавьте поля, которые пользователь должен заполнить перед сохранением шага. В форме входных параметров укажите для каждого поля техническое имя, один из типов string, number, boolean, date, array, object или json, название и подсказку на двух языках. Включите «Обязательное поле», если без этого значения шаг нельзя выполнить. В одном шаге может быть до 50 параметров; в строковые поля можно подставлять переменные автоматизации. Дата передаётся строкой ISO 8601, array принимает только массив, object — только объект, а json подходит для произвольного JSON-значения.

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

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

Шаг 5 — Настройте продолжение автоматизации

Теперь определите, что произойдёт после выполнения шага. Откройте вкладку «Выполнение».

Сначала в блоке «Как продолжить автоматизацию» выберите выходы шага:

• «Один выход „Далее“» — у узла будет один выход, а webhook не должен возвращать branch;
• «Фиксированные ветки» — разработчик заранее задаёт от 2 до 20 веток, их постоянные ключи и названия на двух языках; webhook возвращает ключ выбранной ветки в branch;
• «Ветки после настройки» — собственная встроенная форма создаёт ветки отдельно для каждого настроенного узла; webhook возвращает один из сохранённых ключей.

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

Затем в блоке «Когда продолжить автоматизацию» укажите, когда можно переходить к выбранному выходу:

• «Сразу после отправки webhook» — Senler ставит webhook в очередь и сразу идёт по выходу «Далее». Ответ приложения и поля результата не используются. Этот вариант подходит для команды, итог которой не влияет на дальнейшую схему;
• «После ответа webhook» — Senler ждёт HTTP-ответ до 60 секунд и берёт из него ветку и результат. При ошибке или таймауте повтор шага контролирует Runner;
• «После запроса от приложения» — webhook только запускает долгую операцию. Вместе с запросом приложение получает одноразовые URL и токен завершения, а затем отдельным запросом возвращает результат в течение 7 дней.

Немедленный режим совместим только с выходом «Далее» и шагом без полей результата. Для веток или данных результата выберите ожидание ответа webhook либо отдельного запроса приложения.

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

Шаг 6 — Сохраните неопубликованный шаг

Проверьте заполненные вкладки и нажмите «Сохранить». Senler создаст шаг со статусом «Не опубликован» и вернёт вас к списку. Такой шаг виден только разработчикам приложения — в автоматизациях его пока нет.

Если вы снова открыли неопубликованный шаг и уже подготовили webhook, можно сразу нажать «Сохранить и опубликовать». Для отключённого шага эта кнопка называется «Сохранить и включить».

Перед публикацией укажите основной URL встроенной страницы, если вы выбрали такой режим настройки, и подготовьте webhook.

Шаг 7 — Настройте встроенную страницу, если она нужна

Если вы выбрали «Конструктор настроек», переходите к шагу 8.

В режимах «Встроенная страница в панели» и «Встроенная страница во всплывающем окне» кабинет открывает URL страницы с bootstrap-параметрами версии 2 (senler_mode=automation_step_configurator, тема и язык) и подключает Senler Bridge.

В context.launch приходят тип automation_step_configurator, идентификаторы приложения, проекта, установки, автоматизации и узла, данные шага (id, name, continuation_mode), сохранённый объект configuration и текущие ветки. Зарегистрируйте обработчик сохранения:

import { createSenlerBridgeClient } from "@senler/ui/bridge";

const allowedParentOrigins = new Set(["https://senler.io", "https://aibot.local"]);
const parentOrigin = new URL(document.referrer).origin;
if (!allowedParentOrigins.has(parentOrigin)) {
  throw new Error("Unknown Senler parent origin");
}

const bridge = createSenlerBridgeClient({ parentOrigin });
const context = await bridge.connect();

if (context.launch.type !== "automation_step_configurator") {
  throw new Error("Expected automation step configurator launch");
}

const savedConfiguration = context.launch.configuration;

const currentBranchIds = new Map(
  context.launch.branches.map((branch) => [branch.key, branch.branch_id]),
);
const branchId = (key) => currentBranchIds.get(key) ?? crypto.randomUUID();

const unsubscribeSubmit = bridge.onAutomationStepConfiguratorSubmit(
  async () => ({
    kind: "automation_step_configurator",
    configuration: {
      ...savedConfiguration,
      pipeline_id: "sales",
    },
    branches: [
      { branch_id: branchId("created"), key: "created", title: "Сделка создана" },
      { branch_id: branchId("skipped"), key: "skipped", title: "Создание пропущено" },
    ],
  }),
);

Синхронизация высоты включена в createSenlerBridgeClient по умолчанию. Кабинет использует её для режима «Встроенная страница в панели»; во всплывающем окне высота управляется самим окном. Отключайте syncFrameSize только для формы с намеренно фиксированной высотой: createSenlerBridgeClient({ parentOrigin, syncFrameSize: false }).

configuration сохраняется в узле и передаётся webhook при каждом выполнении. Помимо данных приложения, при открытии формы в нём есть четыре служебных поля: _senler_parameters и _senler_result_fields описывают объявленный контракт, а _senler_parameter_values и _senler_result_bindings содержат текущие значения параметров и привязки результатов к переменным процесса. Покажите их пользователю в своей форме и верните обновлённые _senler_parameter_values и _senler_result_bindings вместе с остальной конфигурацией. Senler сохранит только значения объявленных полей и передаст их webhook отдельно в parameters; служебные ключи в webhook-конфигурацию не попадут.

Для «Веток после настройки» верните хотя бы одну ветку с постоянными branch_id и key. При повторном открытии используйте context.launch.configuration и context.launch.branches, чтобы не терять сохранённые значения и связи на схеме.

Если обработчик выбросит ошибку или вернёт данные неправильной формы, кабинет не сохранит конфигурацию. При размонтировании страницы вызовите unsubscribeSubmit() и bridge.destroy().

Шаг 8 — Обработайте webhook

При выполнении шага Senler отправляет на указанный URL POST-запрос. В режимах «Сразу после отправки webhook» и «После запроса от приложения» доставка ставится в очередь; в режиме «После ответа webhook» Senler удерживает запрос до ответа, но не более 60 секунд.

{
  "event_id": "event-id",
  "idempotency_key": "automation-task-id",
  "event_type": "automation_step",
  "timestamp": "2026-08-20T08:00:00.000Z",
  "app_id": "app-id",
  "installation_id": "installation-id",
  "project_id": "project-id",
  "automation_id": "automation-id",
  "run_id": "run-id",
  "task_id": "task-id",
  "node_id": "node-id",
  "lead_id": null,
  "dialog_id": null,
  "channel_id": null,
  "is_test": false,
  "channel_type": null,
  "platform_user_id": null,
  "step_id": "step-id",
  "step_name": "create_deal",
  "parameters": {
    "amount": 1500
  },
  "configuration": {
    "pipeline_id": "sales"
  }
}

is_test равен true, когда шаг выполняется в тестовом диалоге редактора. В таком запуске поля канала и платформенного пользователя могут быть null; не записывайте тестовые данные как боевые. Поля контекста лида и диалога также могут быть null, особенно в фоновой автоматизации. Запрос подписывается общим секретом приложения по правилам webhook приложения. Проверяйте подпись и допустимый возраст запроса до обработки данных.

В режиме «После ответа webhook» ответ должен быть JSON-объектом. Для шага с ветками верните branch, а объявленные данные конструктора поместите в result:

{
  "branch": "created",
  "result": {
    "deal_id": "deal-42"
  }
}

Для одного выхода не возвращайте branch. Пустое тело допустимо, только если шагу не нужны ветка и обязательные поля результата. Невалидный JSON, неизвестная ветка, неправильный тип результата или ошибка webhook завершают шаг ошибкой.

В режиме «Сразу после отправки webhook» Senler не читает ответ: процесс уже продолжился через выход «Далее».

В режиме «После запроса от приложения» исходный webhook дополнительно содержит объект completion:

{
  "method": "PUT",
  "url": "https://api.senler.io/api/automation-step-executions/task-id/completion",
  "token": "one-time-execution-token",
  "expires_at": "2026-08-27T08:00:00.000Z"
}

После завершения долгой операции отправьте PUT на completion.url, передайте токен как Authorization: Bearer <completion.token> и укажите успешный результат:

{
  "status": "succeeded",
  "branch": "created",
  "result": {
    "deal_id": "deal-42"
  }
}

Для неуспешного завершения передайте status: "failed", стабильный error_code и безопасный error_message. Успешно принятый запрос возвращает { "accepted": true }. URL и токен относятся только к одному выполнению и перестают действовать после срока из expires_at; не сохраняйте токен как общий секрет приложения.

Доставка или задача могут выполняться повторно, поэтому внешнее действие должно быть идемпотентным. Используйте idempotency_key из исходного webhook, чтобы повтор не создал дубликат во внешней системе.

Шаг 9 — Опубликуйте и проверьте шаг

Когда встроенная страница и webhook готовы, вернитесь к списку. В строке нужного шага метка «Не опубликован» показывает текущее состояние. Откройте меню действий ⋯ и выберите «Опубликовать».

Опубликованный шаг появится в каталоге шагов в тех проектах, где приложение установлено и активно. Строка в разделе разработчика показывает название и техническое имя, количество параметров и результатов, способ продолжения и статус. Чтобы изменить шаг, откройте строку или выберите «Изменить» в меню действий.

Сразу после публикации добавьте шаг в автоматизацию тестового проекта. Проверьте каждый разрешённый тип автоматизации, заполнение формы, все выходы и выбранный способ завершения. Убедитесь, что webhook принимает возможный null-контекст, режим ожидания отвечает не дольше 60 секунд, callback укладывается в 7 дней, а повтор с тем же idempotency_key не создаёт дубликат во внешней системе.

Что можно изменить после публикации

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

Можно менять названия, описания, webhook URL и иконку, способ завершения и режим настройки, добавлять необязательные поля и разрешать дополнительный тип автоматизации. Новый способ завершения получают новые узлы; уже добавленные узлы сохраняют прежний вариант.

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

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

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