Application events

How to add an event

An event tells Senler what happened in your application, such as an order payment or a closed deal. An agent can react to it, and a plugin event can also start an automation. The project user connects the required response; creating an event in the application does not start processing by itself.

Events can be declared by Website integration and Plugin applications. The interface section is still called Agent events.

1. Open the form

Open Agent events and select Add. The new event page opens.

2. Name the event for the user

In the user presentation block, enter the title and short description on the Russian tab, then enter the English title and description on the English tab. The user sees the version matching the interface language.

3. Set the system name

Enter the system name that the application sends through the API, for example payment.paid.

In Where the event is available, select at least one option:

• Agent reaction — the user can add the event to their agent;
• Start automation — for a plugin, the event appears among triggers for For dialogs automations.

Both options can be enabled. The separate agent description is shown only when agent reaction is enabled.

If the fact needs different wording for the agent, enable a separate technical description and enter the agent text.

4. Describe the event data

If the event carries data, in the Event data block, select Add field.

In each field card, enter a name, use the type field to select a type option. On the Russian and English tabs, enter the Russian and English description, then enable Required when needed. The remove action removes an unnecessary field. Leave the block empty when the event has no additional data.

5. Save the event

Select Save. Cancel returns to the list without changes.

How to connect an event to an agent

After installing the application, the user opens Plugins in agent settings, selects the application, and adds the required event. A subscription applies only to that agent; other agents in the project do not start reacting automatically.

The application sends the event with exact dialog_id and agent_id values. Senler AI starts the agent only when it is assigned to that dialog and subscribed to the event. Declaring an event alone therefore starts nothing: the user must first connect it to an agent.

How to start 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.

Editing and deletion

On the Agent events page, select Add for a new event or choose an existing event from the list. Use the edit action to change names, descriptions, or the data schema. After changing the schema, make sure the application sends data in the new format.

When an event is no longer used, choose the delete action. Check the event in the confirmation before confirming its deletion. It is immediately removed from every agent subscription, and new calls using that system name are rejected. It also becomes unavailable to automations. Check workflows that used the event and replace their trigger.