Skip to main content
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": { ... }
}
FieldTypeDescription
idstringUnique node ID (UUID recommended)
typestringOne of the node types below
positionobjectVisual coordinates in the workflow builder
dataobjectNode configuration — fields vary by type

​
Node types

TypeDescription
startCallEntry point for telephony calls
endCallTerminates the call
agentNodeLLM-powered conversation step
globalNodeGlobal configuration applied across all agent nodes
triggerEntry point for API-triggered (non-telephony) runs
webhookSends an HTTP request when reached
qaRuns quality analysis on the completed call

​
Node data fields

​
Common fields (all node types)

FieldTypeDefaultDescription
namestringrequiredDisplay name for the node
promptstringrequired*LLM system prompt. *Not required for trigger, webhook, qa nodes
allow_interruptbooleanfalseAllow the caller to interrupt the agent mid-speech
wait_for_user_responsebooleanfalsePause and wait for caller input before continuing
wait_for_user_response_timeoutnumbernullSeconds to wait for input before timing out
detect_voicemailbooleanfalseDetect and handle voicemail on outbound calls
delayed_startbooleanfalseDelay execution of this node
delayed_start_durationnumbernullDelay in seconds
add_global_promptbooleantrueMerge the globalNode prompt into this node’s prompt

​
agentNode — data extraction

FieldTypeDefaultDescription
extraction_enabledbooleanfalseExtract structured data from the conversation
extraction_promptstringnullCustom prompt to guide extraction
extraction_variablesarray[]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

FieldTypeDescription
tool_uuidsstring[]IDs of tools (HTTP API, call transfer, etc.) to attach to this node
document_uuidsstring[]IDs of knowledge base documents available to this node

​
trigger node

FieldTypeDescription
trigger_pathstringUnique UUID that becomes the API trigger endpoint path

​
webhook node

FieldTypeDefaultDescription
enabledbooleantrueWhether this webhook fires when reached
http_methodstring—GET, POST, PUT, PATCH, or DELETE
endpoint_urlstring—Target URL
credential_uuidstringnullUUID of a stored auth credential
custom_headersarray[]Additional request headers [{"key": "...", "value": "..."}]
payload_templateobjectnullRequest body template (supports context variables)

​
qa node

FieldTypeDefaultDescription
qa_enabledbooleantrueEnable QA analysis
qa_system_promptstringnullCustom evaluation prompt
qa_modelstringnullLLM model to use for evaluation
qa_min_call_durationinteger15Minimum call duration in seconds to run QA
qa_voicemail_callsbooleanfalseInclude voicemail calls in QA
qa_sample_rateinteger100Percentage 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."
  }
}
FieldTypeDescription
idstringUnique edge ID
sourcestringID of the originating node
targetstringID of the destination node
data.labelstringShort label shown in the workflow builder
data.conditionstringNatural language condition the LLM evaluates to trigger this edge
data.transition_speechstringOptional 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"
      }
    }
  ]
}