Starting an automation

Start an automation from a plugin event and link an external object to a conversation.

First create a plugin event that allows starting an automation.

1. Enable the trigger and prepare the workflow

For a plugin, enable Start automation. The user installs the plugin in a project, adds the event to a For dialogs workflow, specifies a data variable, and publishes the automation. See App event for the steps.

Send events through POST /api/app-automation-events with the application's project-scoped installation OAuth token and can_manage_agent_events permission. This differs from sending an event directly to an agent with dialog_id and agent_id.

2. Link the external object to a conversation

To let Senler identify the conversation for a payment, first store the external order ID there. The application calls POST /api/app-automation-events/dialogs/:dialogId/variables/:name/add-unique-items, for example with the name order_ids and this body:

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

The method creates an Array dialog variable definition with string items if it does not exist, and adds only missing identifiers. This is a project-owned field, not a hidden application variable. For a new name, let the method create the definition: an existing field must match both its type and data schema.

3. Send the event

Include these fields in the body of POST /api/app-automation-events:

• external_event_id — a unique external fact ID; resend the same fact with the same ID and data;
• type — the declared system event name;
• occurred_at — optional event date and time;
• data — an object matching the declared schema, including required fields; even with no fields, send "data": {};
• routing — the dialog selection rule.

The external_event_id is unique within an application installation: use up to 200 characters, starting with a Latin letter or digit; subsequent characters may also include ., _, :, and -. The system name type starts with a lowercase Latin letter, contains lowercase Latin letters and digits with . or _ separating parts, and is at most 64 characters. If you include occurred_at, use an ISO 8601 date and time.

For example, if payment.paid declares a string field named 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
  }
}

The routing fields dialog_variable_name, dialog_variable_value, and create_dialog_if_missing are required. Senler first looks for an exact string value among the identifiers stored in the specified dialog variable.

The event goes to one dialog, not to every match. Store an external identifier only in the intended conversation: add-unique-items prevents duplicates within its array, but does not prevent the same ID from being added to another dialog.

For fallback lookup, provide lead_variable_name and lead_variable_value together: Senler uses the matching lead's latest active private dialog. The lead variable value can be a string, number, or boolean. Senler stores the external identifier in the selected dialog so that subsequent events can find it directly.

If there is no active private conversation, create_dialog_if_missing: true allows one to be created for the matching accessible lead. On its own, without both fallback lookup fields, this flag creates neither a lead nor a dialog.

4. Check the result

Check status, not just a successful HTTP response:

• scheduled — the event was accepted for processing. This does not yet confirm that the automation finished; check its run.
• ignored — no matching dialog was found, and no run was scheduled.
• duplicate: true — the server has already seen this ID. A completed delivery returns its previous result without starting again.

Store external_event_id with the original request. When retrying, do not change type, data, routing, or occurred_at: changing any of them with the same ID results in 409 Conflict. For example, do not replace the event time with the current time on every delivery attempt.

An ignored result is also stored. If you then add a dialog link and repeat the same request, the server returns ignored again without a new lookup. Prepare the link before sending the event; do not use retries to wait for a dialog to appear.

If agent reaction is also enabled for the event, assigned agents subscribed to it may run in the selected dialog as well. Account for this so the agent and automation do not send the customer duplicate messages.