Automation Steps

In Automation steps, you create steps provided by your application. For example, a CRM application can add a Create deal step, while a mailing service can add an Add subscriber step.

First configure the step in the Cabinet, then prepare the application to run it. When everything is ready, publish the step. It can then be selected in the step catalog and added to an automation graph. The step appears only in projects where the application is installed and active.

Step 1 — Open the step list

Automation steps can be created in a Plugin application. Open the required application in the Developer section and go to Automation steps.

The page contains unpublished, published, and disabled steps. Select Create step.

Step 2 — Complete the General tab

On the step creation page, complete the general information:

1. Enter a technical name, such as create_deal. It must be unique within the application, begin with a Latin letter, and contain no more than 64 Latin letters, digits, _, and - characters.
2. Enter the webhook URL to which Senler sends the request when the step runs.
3. Provide a name and short description in Russian and English. These explain what the step does. The project language determines which version users see.
4. Keep at least one option in Automation types:
   • Dialog automations makes the step available in For dialogs automations and may provide lead, dialog, and channel context;
   • Background automations makes the step available where there may be no lead or dialog.
5. In Step icon, select a preset or upload a PNG, JPEG, or WebP file. The node keeps the application icon as its main image and shows the step icon in the corner.

The technical name cannot change after the first publication. You can enable an additional automation type later, but you cannot remove a published one because saved graphs may use it.

Step 3 — Choose how users configure the step

Now decide what users see after adding the step to an automation. Select one option in Step configuration mode.

Settings builder

Use this option when the step can be configured with regular string, number, Yes / no, date, array, object, or JSON fields. Add the fields on the Parameters and Result tabs, and Senler builds the finished form.

This mode supports One Next output and Fixed branches. Branches after setup does not work with the builder.

Embedded page in the panel

Use this option for a compact custom form. The application interface appears directly in the selected node's side panel. The embedded page's main URL must be set in the application settings; the application's main page does not have to be shown in the project menu.

Embedded page in a dialog

Use this option for a larger form. The user selects Open step settings in the side panel, and the application interface opens in a large dialog. A configured embedded-page main URL is sufficient here as well.

Inputs and results can also be declared for an embedded page. In this mode, Senler does not render them beside the iframe: the embedded form receives field definitions, current values, and result bindings through Senler Bridge and renders the required interface itself. Branches after setup is available only with an embedded page.

Step 4 — Define inputs and result data

If an embedded step does not need declared inputs or results, continue to step 5.

On the Parameters tab, add fields that users must complete before saving the step. In the input parameter form, define each field's technical name, one of the string, number, boolean, date, array, object, or json types, and names and hints in both languages. Enable Required field when the step cannot run without the value. A step can have up to 50 parameters, and string fields may contain automation variables. A date is sent as an ISO 8601 string, array accepts only an array, object accepts only an object, and json is suitable for any JSON value.

On the Result tab, use the result data form to add values returned by the application. For example, Create deal can return the deal ID. Users can save this value to a run variable and use it in later steps. The same seven types are available, with up to 50 result fields.

If a required result is absent or its type does not match the definition, the step fails. Fields not declared in the step are not written to variables.

Step 5 — Configure how the automation continues

Now decide what happens after the step runs. Open the Execution tab.

First, choose the step outputs in How to continue the automation:

• One Next output gives the node one output, and the webhook must not return branch;
• Fixed branches lets the developer define 2–20 branches with stable keys and names in both languages; the webhook returns the selected key in branch;
• Branches after setup lets the custom embedded form create branches separately for each configured node; the webhook returns one of the saved keys.

The continuation mode cannot change after the first publication. A published fixed branch cannot change its technical key or transfer it to another branch.

Then, in When to continue the automation, choose when Senler may follow the selected output:

• Immediately after sending the webhook queues the webhook and follows the Next output immediately. The application response and result fields are ignored. Use it for a command whose outcome does not affect the rest of the graph;
• After the webhook response waits up to 60 seconds for the HTTP response and reads its branch and result. Runner controls step retries after an error or timeout;
• After an application request starts a long-running operation with the webhook. The application receives a one-time completion URL and token and sends the result in a separate request within 7 days.

Immediate mode works only with the Next output and a step without result fields. To use branches or result data, wait for the webhook response or a separate application request.

You can change the completion mode after publication. New nodes receive the current option, while nodes already added to graphs keep their previous option. After changing it, test a new automation and an existing one separately.

Step 6 — Save the unpublished step

Review the completed tabs and select Save. Senler creates a step with the Not published status and returns you to the list. The step is visible only to application developers and is not yet available in automations.

If you reopen an unpublished step after preparing its webhook, you can select Save and publish immediately. For a disabled step, this button is named Save and enable.

Before publication, set the embedded page's main URL if you selected that configuration mode, and prepare the webhook.

Step 7 — Configure the embedded page if needed

If you selected Settings builder, continue to step 8.

For Embedded page in the panel and Embedded page in a dialog, the cabinet opens the page URL with version 2 bootstrap parameters (senler_mode=automation_step_configurator, theme, and language) and connects Senler Bridge.

context.launch contains the automation_step_configurator type, application, project, installation, automation, and node IDs, step data (id, name, and continuation_mode), the saved configuration object, and the current branches. Register a save handler:

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: "Deal created" },
      { branch_id: branchId("skipped"), key: "skipped", title: "Creation skipped" },
    ],
  }),
);

Height synchronization is enabled in createSenlerBridgeClient by default. The Cabinet uses it for Embedded page in the panel mode; a dialog manages its own height. Disable syncFrameSize only for a deliberately fixed-height form: createSenlerBridgeClient({ parentOrigin, syncFrameSize: false }).

configuration is stored in the node and sent to the webhook every time the step runs. When the form opens, it also contains four reserved fields: _senler_parameters and _senler_result_fields describe the declared contract, while _senler_parameter_values and _senler_result_bindings contain current parameter values and result-to-run-variable bindings. Render them in your form and return updated _senler_parameter_values and _senler_result_bindings with the rest of the configuration. Senler saves only values for declared fields and sends them to the webhook separately in parameters; reserved keys are not included in the webhook configuration.

For Branches after setup, return at least one branch with stable branch_id and key values. On subsequent opens, use context.launch.configuration and context.launch.branches so saved values and graph edges are retained.

If the handler throws or returns invalid data, the cabinet does not save the configuration. Call unsubscribeSubmit() and bridge.destroy() when the page unmounts.

Step 8 — Handle the webhook

When the step runs, Senler sends a POST request to the configured URL. In Immediately after sending the webhook and After an application request modes, the delivery is queued. In After the webhook response mode, Senler keeps the request open until the response arrives, for no more than 60 seconds.

{
  "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 is true when the step runs in an editor test dialog. Channel and platform user fields may be null for this run; do not persist test data as production data. Lead and dialog context fields may also be null, especially in a Background automation. The request is signed with the application's shared secret according to the application webhook rules. Verify the signature and acceptable request age before processing the data.

In After the webhook response mode, the response must be a JSON object. For a branched step, return branch and place declared builder data in result:

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

Do not return branch for a single-output step. An empty body is allowed only when the step does not need a branch or required result fields. Invalid JSON, an unknown branch, a mismatched result type, or a webhook error makes the step fail.

In Immediately after sending the webhook mode, Senler does not read the response because the process has already followed the Next output.

In After an application request mode, the original webhook also contains a completion object:

{
  "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"
}

When the long-running operation finishes, send a PUT request to completion.url, pass the token as Authorization: Bearer <completion.token>, and provide the successful result:

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

For a failed completion, send status: "failed", a stable error_code, and a safe error_message. An accepted request returns { "accepted": true }. The URL and token apply to one execution only and expire at expires_at; do not store the token as the application's shared secret.

A delivery or task may run again, so the external action must be idempotent. Use the original webhook's idempotency_key to prevent duplicate changes in the external system.

Step 9 — Publish and test the step

When the embedded page and webhook are ready, return to the list. In the required step row, the Not published label shows the current state. Open the ⋯ actions menu and select Publish.

The published step appears in the step catalog for projects where the application is installed and active. Its row in the Developer section shows the name and technical name, parameter and result counts, continuation mode, and status. To update a step, open its row or select Edit in the actions menu.

Immediately after publication, add the step to an automation in a test project. Check each enabled automation type, the configuration form, every output, and the selected completion mode. Verify that the webhook accepts nullable context, response mode completes within 60 seconds, callbacks arrive within 7 days, and a retry with the same idempotency_key does not duplicate the external change.

What you can change after publication

The current model does not create numbered step revisions: the list stores one current record. After the first publication, Senler blocks incompatible contract changes so saved automations continue to work. Changes to the execution URL apply to the current published step, so verify backward compatibility before saving.

You can update names, descriptions, the webhook URL, the icon, the completion mode, and the configuration mode; add optional fields; and enable an additional automation type. New nodes receive the current completion mode, while nodes already added to graphs keep the previous option.

You cannot change the technical name or continuation mode, remove an already enabled automation type, change the type of a published field, add a new required input parameter, or assign a published branch's technical key to another branch.

Saved nodes use the current configuration mode when opened. Switching to an embedded page alone does not delete parameters, values, or result bindings: they are passed to the application form through reserved configuration fields but are no longer rendered as separate Senler fields. If you remove a parameter, result, or fixed output from the step, the Cabinet marks it as obsolete in a saved node and requires the user to remove it explicitly.

You can disable a published step. It disappears from the catalog for new nodes but is not removed from saved graphs. A disabled step can be published again. Only a step that has never been published can be deleted completely.