Skip to main content

​
Digital agent scripts: branching step graphs

An agent script is a small, directed step graph the agent console walks during a live digital conversation — chat, email, or messaging. The console opens on the script’s start step, shows the agent what to say or do, and follows whichever branch option matches the customer’s answer. The agent never has to remember the flow; the next question is always on screen. Set that against the two tools your agents already have:
  • Macros are static: a prewritten reply, inserted as-is. Nothing reacts to what the customer said.
  • AI reply suggestions are generative: a drafted reply, not a process — the AI has no idea which question must come after the answer.
A script is the third kind: a process the agent can follow on a regulated or multi-branch flow — a refund, a cancellation, an eligibility check — where the right next step depends on the customer’s answer.

​
Where it lives

Open Inbox → Settings → Agent scripts. The page is restricted to owners and admins — writes to the API require an owner or admin key too. Reads are open to every teammate, so the agent console can fetch the graph while a conversation is live. The settings tiles on Inbox → Settings sit next to Macros and Routing; Agent scripts is the tile with the branching icon.

​
The API surface

Five endpoints, all under the /api/v1/inbox base path: Scripts are stored per workspace as a JSONB array on your organization settings — there is nothing to provision and no table to migrate; a saved script is readable by the console immediately. The wire shape is snake case (step_id, next_step_id, start_step_id); the sections below build that shape by hand.

​
Author your first script

You author three things:
  1. Steps. Each step has a step_id, a kind (prompt, question, note, or disposition), an optional title, and a body — what the agent reads, asks, or does.
  2. Branch options. On any step, an options array — each option is a label (the answer the agent picks) and a next_step_id (the step it advances to). A null next step ends the flow.
  3. A start step. start_step_id picks where the console opens; omit it and the flow starts at the first step.
One more authoring habit: give every flow an explicit fallback. Customers rarely answer in your option labels, so end each branch of questions with an escape option (“None of these”, “Customer won’t say”) that lands on a note or disposition step instead of a dead end.

​
Worked example — a three-branch refund intake

The agent asks for the customer’s name, then the order ID, then routes to ship-back, replacement, or a fallback. Rendered tree:
Create it with a single POST:
Before anything is saved, the graph is checked: every step_id unique, every next_step_id resolving to a real step, and start_step_id resolving too. A broken graph returns 422 INVALID_SCRIPT_GRAPH with the reason and persists nothing.

​
Read it back while a conversation is live

After you save — from the dashboard editor or the POST above — the script is immediately readable:
  1. Save the script with Active on (the enabled flag).
  2. Open any live conversation on a channel the script targets (or any channel, if you left channels empty).
  3. Open the script panel in the agent console and pick the script from the picker.
The console walks the graph one step at a time: the current step’s title and body on top, the branch options as clickable choices on a question step, and an explicit end on a disposition step. Because reads are open to every teammate, an agent never needs admin rights to follow a script — only to change one. Patch the same script — rename a step label here — and the console sees it as a new version. PATCH replaces the steps array wholesale, so resend the whole graph on every edit (GET it first if you need the current shape):
The response carries a bumped version — every PATCH increments it, so the console can tell an agent mid-flow that the script changed and reload it. Delete a script the same way:
Deletion is permanent and immediate — keep dormant scripts inactive rather than deleting them.

​
Version and replace semantics

  • Every save bumps version (create starts at 1).
  • PATCH replaces steps in full: there is no per-step edit. The supported flow is offline-edit-then-save — GET the script, edit the JSON locally, PATCH the whole graph back.
  • If a replaced graph keeps the old start step, it survives; otherwise the start falls back to the first step.
  • The graph is validated on the patched result, so you can never save a branch that dangles after a steps-only or start-only patch.

​
The voice parity note

Digital agent scripts are the messaging-side counterpart to the voice queue scripts you already configure on a voice queue — the same idea (a scripted decision path the console walks during a live interaction), applied to chat, email, and messaging instead of a phone call. If your operation scripts calls today, model your digital flows the same way; the step kinds (prompt / question / note / disposition) deliberately mirror the voice script sections.

​
Invariants — what a script never does

A script is display-only guidance. It never terminates a delivery by itself: no message leaves for the customer until the agent sends it, no call is placed, no routing is triggered. The console renders the graph; the human walks it. Treat scripts as inert, auditable guidance buildable and reviewable entirely inside your workspace — every create, update, and delete lands in your audit log with the acting user.

​
Rollout checklist

  1. Draft inactive. Create the script with enabled: false (or Active off in the editor) while you build it.
  2. Trace every branch. Walk each path from the start step to a disposition step; confirm no branch dead-ends and every question has an explicit fallback option.
  3. Dry-run one live conversation. Have a supervisor follow the script on a real thread while it is still inactive, and fix wording before publishing.
  4. Publish. Set enabled: true; confirm the PATCH response’s bumped version.
  5. Audit the change. Check the audit log entry for the create/update with the acting user.
  6. Retire by disabling. Turn a script inactive instead of deleting it; deletes are permanent.

​
See also