Triggers & events

A Trigger is a standing rule an admin sets up on an Agent: when an event like this arrives and looks like that, do this. Once you understand how a Trigger evaluates an event, Sending events stops feeling like a black box, so this page walks through the pieces before you send anything.

The event payload is yours

The payload you POST to an Agent's events endpoint is arbitrary JSON: you decide its shape entirely, whether that's a cart total, a customer record, a support ticket, or anything else your own system produces. AiFlow imposes no schema on it beyond requiring an event_type string and a payload object. A Trigger's conditions are then evaluated against whatever you sent.

Conditions: what counts as a match

A Trigger can define a list of conditions, each shaped like:

{ "field": "customer.phone", "operator": "equals", "value": "+15551234567" }

• field is a dot-path into your posted payload, e.g. customer.phone reaches payload["customer"]["phone"], and items.0.sku reaches the sku key of the first element of an items array.
• operator is one of:

Operator	Checks
equals / not_equals	Exact value match
contains / not_contains	Substring or list membership
exists / not_exists	Whether the field is present at all
gt / gte / lt / lte	Numeric comparison
in / not_in	Value is (or isn't) one of a given set
regex	Value matches a regular expression

• condition_logic decides how multiple conditions combine: "all" (the default) requires every condition to match, "any" requires just one.

An event that matches no configured Trigger is still recorded, it just doesn't cause anything further. See the matched: false response covered in Quickstart.

action_type: what a match causes

When a Trigger's conditions match, its action_type decides what happens:

action_type	Effect
call	Places an outbound phone call
whatsapp	Sends a WhatsApp message
both	Does both
telegram	Sends a Telegram message
agent_task	Runs a silent, headless background task, no call, no message

context_template: turning your data into what the agent says

context_template is a Jinja2 template, rendered against your posted payload. For a call or both Trigger, the rendered text becomes the agent's opening context, the reason it gives for calling. For example, a template like:

You are calling {{ customer.name }} about their cart worth ${{ cart_value }}.

rendered against a payload containing {"customer": {"name": "Jordan"}, "cart_value": 89} gives the agent the context "You are calling Jordan about their cart worth $89" instead of an anonymous cold call. For an agent_task Trigger, the rendered text becomes the task instruction the agent executes.

cooldown_seconds: avoiding repeat fires

A Trigger can set cooldown_seconds to suppress a repeat fire for the same resolved phone number within that window. Worth knowing before you integrate: posting an event that matches a Trigger doesn't guarantee a new call or message every time. If the same recipient already triggered a match recently, AiFlow suppresses the repeat instead of calling them again.

Who configures Triggers

Creating and editing Triggers is an admin action, authenticated with an admin session token rather than the events:write scoped API key an integration uses to send events. See Triggers for the full endpoint reference (create, list, update, delete, and test) and the admin role each endpoint requires. As an integrator sending events rather than managing Triggers, your job isn't to define them: it's to understand what shape of event payload will and won't match what your admin team has already configured, and to read the response your POST gets back to know what happened.

Next

• Triggers: the full CRUD and dry-run test endpoint reference for creating and managing Triggers.
• Sending events: the actual endpoint you call, request and response shapes, and error handling.
• Event log: read back why a specific event did or didn't match after the fact.