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`	Entry point for API-triggered (non-telephony) runs
`webhook`	Sends an HTTP request when reached
`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 webhook fires when reached
`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"
      }
    }
  ]
}

Contribution

Guides

SDKs

Deployment

Workflow Definition Schema

Nodes

Node types

Node data fields

Common fields (all node types)

agentNode — data extraction

agentNode — tools

trigger node

webhook node

qa node

Edges

Validation rules

Minimal example

​Nodes

​Node types

​Node data fields

​Common fields (all node types)

​agentNode — data extraction

​agentNode — tools

​trigger node

​webhook node

​qa node

​Edges

​Validation rules

​Minimal example

Nodes

Node types

Node data fields

Common fields (all node types)

agentNode — data extraction

agentNode — tools

trigger node

webhook node

qa node

Edges

Validation rules

Minimal example