Workflow Definition Schema

The workflow_definition object passed to Create from Definition and Update Agent defines the full conversation graph. It is the same structure the dashboard's visual workflow builder reads and writes — building an agent in the UI produces a workflow_definition under the hood, and anything you can configure visually can equally be expressed here as JSON.

{  "nodes": [...],  "edges": [...]}

Nodes#

Each node represents a step in the conversation.

{  "id": "uuid-string",  "type": "agentNode",  "position": { "x": 100, "y": 200 },  "data": { ... }}

Field	Type	Description
`id`	string	Unique node ID (UUID recommended)
`type`	string	One of the node types below
`position`	object	Visual coordinates in the workflow builder
`data`	object	Node configuration — fields vary by type

Node types#

Type	Description
`startCall`	Entry point for telephony calls
`endCall`	Terminates the call
`agentNode`	LLM-powered conversation step
`globalNode`	Global configuration applied across all agent nodes
`trigger`	Configures API-triggered outbound calls
`webhook`	Sends configured post-call data asynchronously after completion
`qa`	Runs quality analysis on the completed call

Node data fields#

Common fields (all node types)#

Field	Type	Default	Description
`name`	string	required	Display name for the node
`prompt`	string	required*	LLM system prompt. *Not required for `trigger`, `webhook`, `qa` nodes
`allow_interrupt`	boolean	`false`	Allow the caller to interrupt the agent mid-speech
`wait_for_user_response`	boolean	`false`	Pause and wait for caller input before continuing
`wait_for_user_response_timeout`	number	`null`	Seconds to wait for input before timing out
`detect_voicemail`	boolean	`false`	Detect and handle voicemail on outbound calls
`delayed_start`	boolean	`false`	Delay execution of this node
`delayed_start_duration`	number	`null`	Delay in seconds
`add_global_prompt`	boolean	`true`	Merge the `globalNode` prompt into this node's prompt

agentNode — data extraction#

Field	Type	Default	Description
`extraction_enabled`	boolean	`false`	Extract structured data from the conversation
`extraction_prompt`	string	`null`	Custom prompt to guide extraction
`extraction_variables`	array	`[]`	Variables to extract (see below)

Extraction variable schema:

{  "name": "customer_intent",  "type": "string",  "prompt": "What did the customer want to achieve?"}

type is one of string, number, or boolean.

agentNode — tools#

Field	Type	Description
`tool_uuids`	string[]	IDs of tools (HTTP API, call transfer, etc.) to attach to this node
`document_uuids`	string[]	IDs of knowledge base documents available to this node

trigger node#

Field	Type	Description
`trigger_path`	string	Unique UUID that becomes the API trigger endpoint path

webhook node#

Field	Type	Default	Description
`enabled`	boolean	`true`	Whether this post-call webhook is enabled
`http_method`	string	—	`GET`, `POST`, `PUT`, `PATCH`, or `DELETE`
`endpoint_url`	string	—	Target URL
`credential_uuid`	string	`null`	UUID of a stored auth credential
`custom_headers`	array	`[]`	Additional request headers `[{"key": "...", "value": "..."}]`
`payload_template`	object	`null`	Request body template (supports context variables)

qa node#

Field	Type	Default	Description
`qa_enabled`	boolean	`true`	Enable QA analysis
`qa_system_prompt`	string	`null`	Custom evaluation prompt
`qa_model`	string	`null`	LLM model to use for evaluation
`qa_min_call_duration`	integer	`15`	Minimum call duration in seconds to run QA
`qa_voicemail_calls`	boolean	`false`	Include voicemail calls in QA
`qa_sample_rate`	integer	`100`	Percentage of calls to analyse (1–100)

Edges#

Each edge connects two nodes and defines when the transition fires.

{  "id": "edge-uuid",  "source": "node-uuid-a",  "target": "node-uuid-b",  "data": {    "label": "Customer confirms",    "condition": "The customer has confirmed their appointment",    "transition_speech": "Great, I've got that noted."  }}

Field	Type	Description
`id`	string	Unique edge ID
`source`	string	ID of the originating node
`target`	string	ID of the destination node
`data.label`	string	Short label shown in the workflow builder
`data.condition`	string	Natural language condition the LLM evaluates to trigger this edge
`data.transition_speech`	string	Optional speech the agent says before transitioning

Validation rules#

All source and target IDs in edges must reference existing node IDs
All nodes except trigger, webhook, and qa must have a non-empty prompt
Node IDs must be unique within the workflow
Each workflow must have exactly one startCall or trigger node as the entry point

Minimal example#

{  "nodes": [    {      "id": "start-1",      "type": "startCall",      "position": { "x": 0, "y": 0 },      "data": {        "name": "Start",        "prompt": "You are a friendly assistant. Greet the caller and ask how you can help."      }    },    {      "id": "end-1",      "type": "endCall",      "position": { "x": 400, "y": 0 },      "data": {        "name": "End",        "prompt": "Thank the caller and say goodbye."      }    }  ],  "edges": [    {      "id": "edge-1",      "source": "start-1",      "target": "end-1",      "data": {        "label": "Done",        "condition": "The caller's question has been answered and they want to end the call"      }    }  ]}