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 "0 9 * * 1-5" with 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 the agent with message as the turn (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. tz="user" reads it in a user's agent's (or channel's) user's timezone, following them when they move (UTC while they have none; an account agent refuses it, having no user); a wake-up reads it in the timezone of the user whose conversation it wakes.

Every agent turn is told the date and time, so a schedule's message can say "last month" or "this week" and mean it.

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, the agent's own user's; event names one of the integration's app events (channel_message for Slack, contact_created for HubSpot; list them with connection.events()) and each keyword argument narrows it the way the integration takes it, like channel="C0123ABCD" (a Slack channel's id: slack.lookup("channel") lists them). message is what the agent is told with every event, above it. A thread (a Slack thread) stays one conversation, so the agent's replies land in it. conversation keys conversations yourself, a template over the event as the app sent it: "issue-{issue.number}" keeps everything about one issue in one. A channel subscribes to the same events (channel.subscribe(noclick.OnEvent(...))), each posted in the room. The connection needn't be connected yet: the trigger is error until it is.

One of NoClick's own events (the types noclick.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 (its turn finishing), and a chain of agents waking each other this way stops five turns deep. A channel subscribes to the same events (channel.subscribe(noclick.OnPlatformEvent(...))).

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 batch_size above 1 (up to 25), one turn takes up to that many waiting messages at once, as a JSON list, for work that's cheaper in bulk. queue is a Queue or its name, the agent's own user's.

Delivery follows the queue's rules: a turn that finishes acks its messages; a turn that fails hands them back for another try (after 30 seconds per attempt they've had), and a message that fails the queue's max_attempts times becomes a dead letter, the turn's error its last_error. Each turn is a conversation of its own, unless conversation keys it from the message (one message a turn only; turns of one conversation take their turn one at a time). 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, the trigger's status is error saying why, and it carries on by itself once there's money to spend again (it looks every half minute).

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 for a person: 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, say, a queue's turns waiting for money, or its turns failing the same way five times in a row, which stops it until the agent is resumed).