Workflow Nodes

Every node in a definition is an envelope with the same shape:

{
  "id": "n_call",              // ^[a-z0-9_]{1,64}$, unique within the workflow
  "type": "agent",             // one of the types below
  "name": "Qualify",           // optional display name
  "config": { ... },           // type-specific, documented below
  "cases": [ ... ],            // ordered routing conditions (most types)
  "on_no_match": "n_end_x"     // optional per-node fallback
}

Most nodes route onward through cases — ordered conditions where the first match wins (see Conditions and variables). time nodes use a single to instead, and end nodes have no exit. When no case matches, the execution moves to the node’s on_no_match, or the definition-wide one if the node doesn’t declare its own. The Node Types API returns this catalog programmatically — every parameter with defaults and bounds, generated from the same models that publish enforces.

Definition limits: at most 200 nodes, 25 cases per node, 10 effects per case, 50 declared start fields, and 512 KB of definition JSON.

start

The entry point. Exactly one per workflow, referenced by entry_node_id, and it must have at least one case. It declares the contact fields the workflow accepts — the schema that single runs and campaign uploads are validated against.

Config	Type	Default	Notes
`trigger.kind`	string	required	`manual` — contacts enter via the run endpoint or campaigns
`fields`	array	`[]`	Up to 50 declared fields
`fields[].name`	string	required	`^[a-zA-Z_][a-zA-Z0-9_-]{0,63}$`
`fields[].type`	string	`string`	`string`, `number`, `boolean`, `timestamp`, `phone`, `email`, `url`, `json`
`fields[].required`	boolean	`false`	Rows missing a required field fail validation

Four system fields are always accepted without declaring them: reference_id, mobile_number, name, email. Declaring one (for example to make mobile_number required) refines the built-in rather than duplicating it.

{
  "id": "n_start",
  "type": "start",
  "config": {
    "trigger": { "kind": "manual" },
    "fields": [
      { "name": "mobile_number", "type": "phone", "required": true },
      { "name": "loan_amount", "type": "number" },
      { "name": "city", "type": "string" }
    ]
  },
  "cases": [
    { "when": { "always": true }, "then": { "to": "n_call" } }
  ]
}

Declared fields become entry.* variables — entry.loan_amount in the example — usable in any downstream condition. Typed fields are coerced at upload, so "42000" in a CSV compares numerically.

agent

Places a call with one of your Bolna voice agents and waits for it to finish.

Config	Type	Default	Notes
`agent_id`	string	required	The agent to dial with
`recipient`	operand	`{"var": "entry.mobile_number"}`	Who to call
`from_number`	string	`null`	Originating number override
`timeout_s`	integer	`3600`	60–86400. The case branch on `call.status` `"timeout"` fires if the call hasn’t concluded in time
`variables`	object	`{}`	Values passed to the agent as prompt variables, e.g. `{"customer_name": {"value": {"var": "entry.name"}}}`

After the call, the node writes call.* variables and its cases branch on them:

call.status — completed, busy, no_answer, failed, voicemail, cancelled, rejected, timeout, or error
call.duration_s — call duration when known
call.error — set when status is error (for example missing_recipient when the recipient variable is blank)

{
  "id": "n_call",
  "type": "agent",
  "name": "Qualify",
  "config": {
    "agent_id": "<agent_id>",
    "timeout_s": 3600,
    "variables": {
      "customer_name": { "value": { "var": "entry.name" } }
    }
  },
  "cases": [
    { "when": { "cmp": "==", "left": { "var": "call.status" }, "right": { "const": "completed" } },
      "then": { "to": "n_extract" } },
    { "when": { "cmp": "in", "left": { "var": "call.status" }, "right": { "const": ["busy", "no_answer"] } },
      "then": { "to": "n_retry" } }
  ]
}

Each agent node produces a regular call execution with its own transcript and recording.

extraction

Exposes fields your agent extracted from the call — its dispositions — as extraction.* variables for branching.

Config	Type	Default	Notes
`agent_node_id`	string	required	The agent node whose call to read from
`selected`	array of strings	required	The extraction field names this node exposes; publish requires a non-empty list

An extraction node must directly follow its linked agent node. At publish, the field types are filled in server-side from the agent’s dispositions — numeric dispositions compare numerically.

{
  "id": "n_extract",
  "type": "extraction",
  "config": {
    "agent_node_id": "n_call",
    "selected": ["call_score", "engagement_intent"]
  },
  "on_no_match": "n_end_cold",
  "cases": [
    { "when": { "cmp": ">", "left": { "op": "+", "args": [ { "var": "extraction.call_score" }, { "var": "extraction.engagement_intent" } ] },
                "right": { "const": 80 } },
      "then": { "to": "n_end_hot", "effects": [ { "set_value": { "state.lead": { "const": "hot" } } } ] } },
    { "when": { "cmp": ">", "left": { "var": "extraction.call_score" }, "right": { "const": 40 } },
      "then": { "to": "n_end_warm" } }
  ]
}

api

Calls an external HTTP endpoint, maps values out of the response, and branches on the result.

Config	Type	Default	Notes
`method`	string	`POST`	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`
`url`	string	required	The host must be literal (no variables in the host)
`headers`	object	`{}`	`x-internal*` header names are reserved
`body`	any	`null`	JSON body; string values may embed `{placeholder}` references
`timeout_s`	integer	`30`	1–300
`follow_redirects`	boolean	`false`
`response_map`	object	`{}`	Maps names to dotted paths into the response, e.g. `{"score": "json.data.score"}`
`variables`	object	`{}`	Resolves `{placeholder}` references in the URL, headers and body

After the request, cases branch on response.*:

response.status — the HTTP status code as a number. A 4xx/5xx is not retried away — it reaches your cases so you decide what happens.
response.<name> — every response_map entry.
response.error — "transport" on DNS failure, connection refusal or timeout (no response.status in that case).

{
  "id": "n_record",
  "type": "api",
  "name": "Record the promise",
  "config": {
    "method": "POST",
    "url": "https://api.example.com/promises",
    "body": { "customer": "{customer}", "date": "{promised_date}" },
    "variables": {
      "customer": { "value": { "var": "entry.reference_id" } },
      "promised_date": { "value": { "var": "extraction.promised_date" } }
    },
    "response_map": { "promise_id": "json.id" }
  },
  "cases": [
    { "when": { "cmp": "==", "left": { "var": "response.status" }, "right": { "const": 200 } },
      "then": { "to": "n_end_recorded" } },
    { "when": { "cmp": "==", "left": { "var": "response.error" }, "right": { "const": "transport" } },
      "then": { "to": "n_end_unreachable" } },
    { "when": { "always": true }, "then": { "to": "n_end_failed" } }
  ]
}

time

Waits, then moves on. The only node with a single exit — it takes to instead of cases.

Config	Type	Default	Notes
`delay`	object	—	`{"days": 0, "hours": 0, "minutes": 30}` — relative wait, up to 365 days
`at`	string or operand	—	Absolute timestamp: an ISO datetime with offset, or `{"var": "..."}` reading a `timestamp` field
`timezone`	string	`null`	IANA zone, only valid with a variable `at`

Exactly one of delay or at must be set.

{
  "id": "n_wait",
  "type": "time",
  "config": { "delay": { "hours": 24 } },
  "to": "n_followup_call"
}

retry

Re-runs an earlier node on a schedule — the only legal way to close a cycle in the graph. Any other loop back upstream is rejected at publish with unbounded_cycle.

Config	Type	Default	Notes
`target_node_id`	string	required	The node to re-run
`attempts`	array	required	1–10 schedule entries, each `{"delay": {...}}` or `{"at": ...}` — one entry per retry

Each time the execution reaches the retry node it consumes the next attempt: waits out that entry’s schedule, then jumps back to the target. Once all attempts are consumed, the node’s cases are evaluated instead — that’s your “gave up” path. The target therefore runs at most attempts + 1 times.

{
  "id": "n_retry",
  "type": "retry",
  "config": {
    "target_node_id": "n_call",
    "attempts": [
      { "delay": { "minutes": 2 } },
      { "delay": { "minutes": 2 } },
      { "delay": { "minutes": 2 } }
    ]
  },
  "cases": [
    { "when": { "always": true }, "then": { "to": "n_end_unreachable" } }
  ]
}

aisensy_whatsapp

Sends a WhatsApp template message through your connected AiSensy account.

Config	Type	Default	Notes
`template_name`	string	required	The approved template’s name
`language`	string	required	The template’s ISO language code, e.g. `en` or `en_US` — never a display name like `English`
`recipient`	operand	required	Who to message, e.g. `{"var": "entry.mobile_number"}` — no default
`variables`	object	`{}`	Template placeholder values keyed by index — `"1"`, `"2"`, … contiguous from 1
`campaign_name`	string	`null`	Records which AiSensy campaign the template came from; display-only

{
  "id": "n_wa",
  "type": "aisensy_whatsapp",
  "config": {
    "campaign_name": "lead_warmup",
    "template_name": "followup_v2",
    "language": "en",
    "recipient": { "var": "entry.mobile_number" },
    "variables": {
      "1": { "value": "{entry.name}", "required": true }
    }
  },
  "cases": [
    { "when": { "cmp": "==", "left": { "var": "whatsapp.status" }, "right": { "const": "sent" } },
      "then": { "to": "n_end_messaged" } },
    { "when": { "always": true }, "then": { "to": "n_end_failed" } }
  ]
}

Cases branch on whatsapp.status (sent or failed), with whatsapp.message_id and whatsapp.error alongside.

end

Terminates the execution.

Config	Type	Default	Notes
`label`	string	required	Becomes the execution’s `termination_reason` and a key in campaign reports
`outcome`	string	required	`success`, `failure` or `neutral` — rolls up into campaign and version counters

{
  "id": "n_end_reached",
  "type": "end",
  "config": { "label": "reached", "outcome": "success" }
}

Design your endings deliberately: every distinct label becomes a row in the campaign report, and the outcomes drive the success_count / failure_count / neutral_count rollups everywhere.

Quickstarts

Phone Numbers & Calling Setup

Outbound Calling

Workflows

Inbound Calling

Native Telephony Integrations

Managing Live Calls

Prompting & Personalization

Tools & Function Calling

Post-Call & Analytics

No-Code & Automation

SIP Trunking Guide

start

agent

extraction

api

time

retry

aisensy_whatsapp

end

Next Steps

Conditions and variables

Node Types API

​start

​agent

​extraction

​api

​time

​retry

​aisensy_whatsapp

​end

​Next Steps

Conditions and variables

Node Types API

start

agent

extraction

api

time

retry

aisensy_whatsapp

end

Next Steps