Sequences

A job is a sequence of steps in the order they happen. Each step has a time (when), a channel, a title, the message that goes out, and a gate that says whether the step runs on its own or waits for the owner's OK. Ask Dash, the Agents page and the mobile app all show the same sequence.

Read a sequence

GET /v1/agents/{id}/sequence

{
  "data": {
    "agent_id": 42,
    "when": "Every day at 6:00pm",
    "mode": "ask",
    "messages_complete": false,
    "steps": [
      { "tool": "get_late_returns", "when": "Every day at 6:00pm", "channel": "check", "title": "Look up late returns", "message": null, "gate": "none", "locked": true, "ask_reason": null, "branch": null },
      { "tool": "send_sms_template_to_booking", "when": "Then", "channel": "text", "title": "Text the customer about a booking", "message": null, "gate": "ask", "locked": true, "ask_reason": "goes to your customers", "branch": null }
    ]
  }
}

An agent whose sequence has never been edited still returns one, built from the agent's tools, approval modes and trigger.

Step fields

Field	Values	Notes
when	free text, up to 60 characters	The first step carries the trigger ("Every Monday at 8:00am"); later steps usually read "Then"
channel	text, email, chat, charge, check, update, filter	check is a look-up; update is a change to a record. filter is read-only, see below
title	up to 120 characters	In the owner's words
message	up to 1000 characters, or null	The words that go out on a text, email or chat step. Placeholders like {{first_name}}, {{start_time}} and {{supplier_name}} are filled at send time
gate	auto, ask, none	none is set on check and filter steps; a look-up can't be made to ask
locked	boolean	A locked step keeps its gate whatever you send
ask_reason	money, cannot be undone, goes to your customers, or null	Why a locked step always asks
branch	{ "if": "...", "steps": [...] } or null	At most one branch per sequence, one level deep
tool	tool name	Optional on write: a step without a tool keeps the tool the built step had in that position
via	email, whatsapp	Only on a send_to_owner step: how the owner gets it. Its channel is always email

messages_complete is true when every text, email and chat step has a message. The Agents page and Ask Dash won't turn a job on until it is. PUT /v1/agents/{id} does not check this, so read the sequence before you send "is_enabled": true.

Steps that always ask

Any step that takes or returns money, can't be undone, or sends something to a customer is locked with gate set to ask. That covers every customer text and email. These steps wait for an OK in both modes, and a "gate": "auto" you send for one is ignored.

The filter step

An event or schedule agent limited to some items, or some bookings, gets a filter step first ("Only bookings for ..."). The filter comes from trigger_config.filter, not from the stored steps. Change the trigger with PUT /v1/agents/{id} to change it, and leave the filter step out when you write the sequence back: PUT /v1/agents/{id}/sequence rejects the filter channel.

Long sequences

A sequence shows at most 12 steps. When an agent has more, the extra look-ups fold into one check step titled "And 5 more look-ups" with tool null. Every step that sends, writes or takes money stays in the list.

Replace a sequence

PUT /v1/agents/{id}/sequence

{
  "mode": "auto",
  "steps": [
    { "channel": "check", "title": "Look up late returns" },
    { "channel": "text", "title": "Return reminder", "message": "Hi {{first_name}}, your {{what_they_booked}} was due back at {{end_time}}. We are open until 6:30 today." }
  ]
}

• steps replaces the whole list (1 to 12 steps).
• mode is optional. auto lets every unlocked step run on its own; ask puts every unlocked step that changes something behind an OK. Locked steps keep asking either way.
• The agent's tool_approval_modes are rewritten from the gates, so the agent runs exactly the sequence you see.

The response has the same shape as the read.

Errors

Status	When
404	The agent doesn't belong to this business
422	No steps or more than 12, an unknown channel (including filter), a gate other than auto or ask, a title over 120 characters, a message over 1000 characters
403	The key lacks agents:write