Sending an event to an agent

Send an event to a specific agent in a selected dialog.

First create an event with agent reaction enabled.

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 inside target. Senler AI starts the agent only when it is assigned to that dialog and subscribed to the event.

How to send an event to a specific agent

Use POST https://api.senler.io/api/app-agent-events with the application's project-scoped OAuth token and can_manage_agent_events permission. A project API key or user-scoped OAuth access does not work for this method: the request must belong to an installation of the sending application.

For example, for payment.paid with a string field named order_id, send this JSON body, replacing the dialog and agent IDs with your own:

{
  "external_event_id": "payment:42",
  "type": "payment.paid",
  "target": {
    "dialog_id": "0123456789abcdef01234567",
    "agent_id": "019d0000-0000-7000-8000-000000000001"
  },
  "data": { "order_id": "order-42" }
}

Pass the token in Authorization: Bearer <access_token> and set Content-Type: application/json. Both the dialog and agent must belong to the installation's project. The method neither searches for a conversation nor assigns the agent to it: do this before sending the event.

data must match the declared fields; send {} if there are none. The optional occurred_at contains the event time in ISO 8601. For this method, external_event_id is limited to 128 characters: start with a Latin letter or digit; subsequent characters may also include ., _, :, and -. Use a unique ID within the application installation.

Check status in the response, not just accepted: true:

scheduled — the agent run is scheduled; this is not a finished answer. senler_event_id contains the Senler event ID;
ignored — the agent is not subscribed to the event, no run occurred, and senler_event_id is null;
duplicate: true — the server has already seen this ID. Retrying a completed delivery returns the previous result without a second run.

For retries, keep the same external_event_id and unchanged type, target, data, and occurred_at. Different data with the same ID returns 409 Conflict. An ignored result is also stored: enabling the subscription later does not turn a retry of the previous request into a new run. Connect the event to the agent before sending it.

This method targets an agent, not an automation. To start an automation, use the separate method with routing.