Flows & the Studio

The Studio is a drag-and-drop canvas where you compose a flow from nodes and wire them together. Each node carries configuration in its inspector and references session variables captured from user input. Use the built-in simulator to step through a flow before you publish.

Add nodes by dragging them from the palette, double-clicking a palette item, or pressing its number key (1–9). Collapse the palette with the chevron; a slim rail keeps a re-open button in view.

A flow graph supports these node types:

A menu node shows a list of options; each option's key becomes a source handle you wire to the next step. The prompt is just a header — the numbered options are appended automatically at runtime, so you never re-type the list into the prompt.

{
  "prompt": "Choose an option:",
  "options": [
    { "key": "1", "label": "Check balance" },
    { "key": "2", "label": "Buy airtime" }
  ]
}
// renders →  Choose an option:
//            1. Check balance
//            2. Buy airtime

The database node reads and writes your project tables at runtime. Choose an operation (read / write / update / delete), the target table, a filter and the fields to map into session variables. This is the same data your REST API sees.

Every value a flow captures is stored as a session variable. Insert one into any text field with {{name}}. The caller's number is always available as {{msisdn}}.

{
  "prompt": "Enter amount (GHS):",
  "variable": "amount"        // captured input → {{amount}}
}

When a variable holds a structured value — an API response saved with saveAs, or a whole database row — reach into it with a path. Use dots for object fields and either dots or brackets for array indices.

{{member.full_name}}        // object field
{{member.address.city}}     // nested field
{{items[0].id}}             // array element (bracket)
{{items.0.id}}              // array element (dotted)

A condition node holds an ordered list of branches. Each branch compares a variable against a value; the first match routes through a handle named after that branch's id. If none match, the else handle is taken.

{
  "branches": [
    { "id": "b1", "variable": "amount", "operator": "gt", "value": "0" }
  ]
}
// b1  → amount > 0     else → fallthrough

The API node calls an external HTTP endpoint, interpolating variables into the URL, headers and body, then saves the response into the variable named by saveAs. It routes through next on success and error on a non-2xx response or timeout.

Headers and the request body are edited as key/value pairs in the inspector. The body is sent as a JSON object on POST requests; every value supports {{variable}} interpolation.

{
  "method": "POST",
  "url": "https://api.example.com/transfer",
  "headers": { "Authorization": "Bearer {{env.API_TOKEN}}" },
  "body": { "msisdn": "{{msisdn}}", "amount": "{{amount}}" },
  "timeoutMs": 8000,
  "saveAs": "transfer"         // response → {{transfer}}
}

Pick an operation and a table. A read matches rows with a filterand maps the first row's columns into variables; write / update apply an assignments map.

{
  "operation": "read",
  "collection": "prices",
  "filter": { "name": "{{crop}}" },
  "saveAs": "priceRow"          // columns → {{price}}, {{unit}}, …
}

{
  "operation": "write",
  "collection": "deposits",
  "assignments": {
    "amount": "{{amount}}",
    "msisdn": "{{msisdn}}"
  },
  "saveAs": "depositId"         // new row id → {{depositId}}
}

For update and delete, set rowIdto the row's id (often a captured variable).

The operation node computes new values from existing variables using a safe, whitelisted arithmetic grammar — never eval. It holds an ordered list of assignments, each writing an expression result into a target variable. Assignments run top-to-bottom, so a later one can build on an earlier target.

{
  "assignments": [
    { "target": "new_balance", "expression": "{{balance}} + {{amount}}" },
    { "target": "display",     "expression": "fixed({{new_balance}} / 100, 2)" }
  ]
}

Expressions support the operators + - * / %, parentheses, and the functions min, max, round, abs, floor, ceil and fixed(x, n). Variables are interpolated with {{...}} before evaluation.

The SMS node queues a message (fire-and-forget, so the USSD response stays fast). It defaults to the caller when to is empty.

{
  "to": "{{msisdn}}",
  "message": "Payment of GHS {{amount}} received."
}

Drag from a source handle to a target to connect two nodes. To remove a connection, hover the edge and click the × at its midpoint, or select it and press Delete. Every edit is captured in an undo history — reverse and replay changes with the toolbar buttons or Ctrl/⌘+Z and Ctrl/⌘+Shift+Z.

The canvas has shortcuts for common actions (they never fire while you're typing in a field). Open the keyboard menu in the toolbar for the full list.

When you publish (or the simulator can't start), the flow is validated. Problems tied to a specific node are listed as clickable items — selecting one jumps to that node and outlines it in red on the canvas so the fix is obvious. The highlight clears as soon as you edit the graph.