Developer Guides
Workflow Definition Schema Schema reference for the workflow_definition object used in the Agents API
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" : [ ... ] } Each node represents a step in the conversation.
{ "id" : "uuid-string" , "type" : "agentNode" , "position" : { "x" : 100 , "y" : 200 }, "data" : { ... } } Field Type Description idstring Unique node ID (UUID recommended) typestring One of the node types below positionobject Visual coordinates in the workflow builder dataobject Node configuration — fields vary by type
Type Description 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
Field Type Default Description namestring required Display name for the node promptstring required* LLM system prompt. *Not required for trigger, webhook, qa nodes allow_interruptboolean falseAllow the caller to interrupt the agent mid-speech wait_for_user_responseboolean falsePause and wait for caller input before continuing wait_for_user_response_timeoutnumber nullSeconds to wait for input before timing out detect_voicemailboolean falseDetect and handle voicemail on outbound calls delayed_startboolean falseDelay execution of this node delayed_start_durationnumber nullDelay in seconds add_global_promptboolean trueMerge the globalNode prompt into this node's prompt
Field Type Default Description extraction_enabledboolean falseExtract structured data from the conversation extraction_promptstring nullCustom 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.
Field Type Description 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
Field Type Description trigger_pathstring Unique UUID that becomes the API trigger endpoint path
Field Type Default Description enabledboolean trueWhether this webhook fires when reached http_methodstring — GET, POST, PUT, PATCH, or DELETEendpoint_urlstring — Target URL credential_uuidstring nullUUID of a stored auth credential custom_headersarray []Additional request headers [{"key": "...", "value": "..."}] payload_templateobject nullRequest body template (supports context variables)
Field Type Default Description qa_enabledboolean trueEnable QA analysis qa_system_promptstring nullCustom evaluation prompt qa_modelstring nullLLM model to use for evaluation qa_min_call_durationinteger 15Minimum call duration in seconds to run QA qa_voicemail_callsboolean falseInclude voicemail calls in QA qa_sample_rateinteger 100Percentage of calls to analyse (1–100)
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 idstring Unique edge ID sourcestring ID of the originating node targetstring ID of the destination node data.labelstring Short label shown in the workflow builder data.conditionstring Natural language condition the LLM evaluates to trigger this edge data.transition_speechstring Optional speech the agent says before transitioning
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
{ "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" } } ] }