Triggers

A schedule: a five-field cron expression (minute, hour, day of month, month, day of week: numbers, *, ranges, steps, lists and month or day names) read in a timezone, so new Cron("0 9 * * 1-5", { tz: "America/New_York" }) means 9am New York time on weekdays, daylight saving included. When both day fields are restricted a run must match both. An agent's schedule wakes it with message (each run a conversation of its own); a wake-up's every wakes one conversation at each time, with its note (a routine: agent.wake); a channel's posts message in the room; an app's (invite-only beta) calls one of its paths.

A URL that wakes the agent: each POST to it is a turn, its body the message (a JSON body is passed as JSON). The URL is AgentTrigger.url; anyone who has it can wake the agent, so keep it like a key. It stays the same while a trigger of that name stays on the agent. message is what the agent is told with every delivery, above the body.

An app event from one of the agent's connections, such as a Slack message or a new HubSpot contact. connection is a Connection or its name, looked up for the agent's own user; event names one of the integration's app events (channel_message for Slack, contact_created for HubSpot; connection.events() lists them) and filters narrow it the way the integration takes them, like { channel: "C0123ABCD" } (a Slack channel's id: slack.lookup("channel")). message is what the agent is told with every event, above it. A thread (a Slack thread) stays one conversation. The connection needn't be connected yet: the trigger is error until it is.

One of NoClick's own events (the types Event.types() lists, as your webhooks receive them): an operation failing, a connection breaking, a channel halting, a workflow's run failing, an agent built in the app asking for you, a payment going through. type names one, and * matches the rest of a name ("operation.*"); filters are dotted paths into the event's data and the values they must have. message is what the agent is told with every event, above it; conversation keys conversations by a template over the event ("connection-{data.id}"), else each event is a conversation of its own. The agent hears its user's events, and an agent of your account's hears every event, your users' included. It never hears what its own turns caused, and a chain of agents waking each other this way stops five turns deep. A channel subscribes to the same events (channel.subscribe(new OnPlatformEvent(...))).

await ops.addTrigger(new OnPlatformEvent("workflow.run.failed", {
  conversation: "workflow-{data.workflow_id}", message: "A workflow failed. Find out why; pause it if it's useless.",
}));

Each message on a queue becomes a turn: the agent reads message (its standing instructions, if any) and then the message's JSON body. With batchSize above 1 (up to 25), one turn takes up to that many waiting messages as a JSON list. queue is a Queue or its name, looked up for the agent's own user. A turn that finishes acks its messages; one that fails hands them back (after 30 seconds per attempt they've had), and a message that fails the queue's maxAttempts times becomes a dead letter, the turn's error its lastError. Each turn is a conversation of its own, unless conversation keys it from the message (one message a turn only); concurrency (1 to 50) runs up to that many turns at once; while the agent is paused, messages wait.

When the agent's budget, its user's cap or your account's funds run out, the trigger pauses instead of failing turns: messages wait with their attempts unchanged, its status is error saying why, and it carries on by itself once there's money to spend again.

One thing that wakes an agent, as agent.triggers() reads it. kind is cron, webhook, event, platform, queue, email, call or approval. spec is its definition (name for a webhook; connection, event and filters for an app event; type and filters for a NoClick event; message and conversation where they were given; inbox_id and address for email; phone_number_id and number for calls; cron, tz and message for a schedule; queue, batch_size and concurrency for a queue; tools, the ones policy may hold, for an approval). An approval trigger is there while your policy may hold one of its tools: an answered approval wakes it in the held call's conversation. status is active, paused (agent.pause()) or error, with error saying why it can't fire (a connection that isn't connected, or its turns failing the same way five times in a row, which stops it until the agent is resumed). defined is true for the kinds your code defines (cron, webhook, event, platform, queue).