# Node Types Reference This is intended as a **quick reference** (not a tutorial) and works for chatbot engines, workflow DSLs, and LLM orchestration flows. Each node type is documented with: * YFlow syntax - How to write it in YFlow format * Customer v2 data structure - The corresponding TypeScript interface from packages/model/src/ * Field mapping - How YFlow fields map to Customer v2 fields


Node Type	YFlow `type:`	Customer v2 `NodeType`	Purpose
Start	(implicit)	START	Flow entry point
End	end	END	Flow termination
Say	say	SAY	Output text/speech
Agent	agent	AGENT	GenAI conversation
Menu	menu	MENU	DTMF phone menu
API	api	API_CALL	REST API call
Transfer	transfer	TRANSFER	Call transfer
Tools	tools	TOOLS	MCP tool binding
Branch	branch	BRANCH	Conditional routing
Set	set	SET	Assign/compute variables

#### Common Node Properties These properties apply to **most or all node types**, regardless of whether the node is `message`, `decision`, `api_call`, etc. ``` nodes: - main_agent: type: agent pos: [200, 100] # Optional: UI position [x, y] # ... node-specific fields ```


Property	Type	Required	Description
pos	[x, y]	No	UI canvas position. If omitted, auto-layout applies.

#### Customer v2 Mapping: ``` // Source: packages/model/src/flow/node-metadata.interface.ts interface NodeMetadata { x: number; // ← pos[0] y: number; // ← pos[1] } ``` #### Behavior: * If pos is present → use specified coordinates * If pos is omitted → auto-layout calculates position on import * Export always includes pos to preserve user's layout #### Start Node The start node is the entry point to the flow - it's whichever node is named start: ``` nodes: - start: next: main_menu ``` **Customer v2 Data Structure:** ``` // Source: packages/model/src/flow/nodes/start-node.interface.ts interface StartNode extends Node { readonly type: NodeType.START; // ← YFlow: node named "start" } // Source: packages/model/src/flow/node.interface.ts interface Node { nodeId: string; // ← Generated UUID type: NodeType; // ← YFlow: type field exits: Exit[]; // ← YFlow: next field metadata: NodeMetadata; // ← UI position { x, y } } ``` **Field Mapping:** Field Mapping describes how values from a source structure are copied, transformed, or derived into target variables used by subsequent nodes.


YFlow	Customer v2 Field	Notes
start: (key)	nodeId (generated)	Node identifier
(implicit)	type: NodeType.START	Auto-detected from node named start
next:	exits[0].nodeId	Single exit to next node

#### End Node: End nodes terminate the flow. They require explicit type: end: ``` nodes: # Named end node - end_1: type: end # Multiple end points for different outcomes - success_end: type: end - failure_end: type: end # Typical pattern: say node leading to end - farewell: type: say message: Thank you for calling. Goodbye! next: end_1 ``` Note: The target next: end routes to a node named end. If you have multiple end points, name them descriptively (e.g., end\_1, success\_end). **Customer v2 Data Structure:** ``` // Source: packages/model/src/flow/nodes/end-node.interface.ts interface EndNode extends Node { readonly type: NodeType.END; // ← YFlow: type: end } ``` **Field Mapping:**


YFlow	Customer v2 Field	Notes
end_1: (key)	nodeId (generated)	Node identifier
type: end	type: NodeType.END	Direct mapping
(no exits)	exits: []	End nodes have no exits

#### Say Node Say nodes output text or speech. They require explicit type: say: ``` nodes: # Standard say node - greeting: type: say message: Welcome to our service! next: main_agent # Say with variable interpolation - goodbye_message: type: say message: { goodbye_message } # From slot value next: end # Say with options (Possible Future enhancement) - detailed_greeting: type: say message: text: Welcome to our service! voice: Matthew # Override flow voice speed: 1.1 # Future: speech rate lang: # Future: language variants en-US: Welcome to our service! es-MX: ¡Bienvenido a nuestro servicio! fr-CA: Bienvenue à notre service! next: main_agent # Multi-line say using YAML literal block - help_message: type: say message: | I can help you with: - Account questions - Billing issues - Technical support next: main_agent ``` **Customer v2 Data Structure:** ``` // Source: packages/model/src/flow/nodes/say-node.interface.ts interface SayNode extends Node { readonly type: NodeType.SAY; // ← YFlow: type: say message: string; // ← YFlow: message field } ``` **Field Mapping:**


YFlow	Customer v2 Field	Notes
greeting: (key)	nodeId (generated)	Node identifier
type: say	type: NodeType.SAY	Direct mapping
message:	message	Text/speech content
next:	exits[0].nodeId	Single exit to next node

Note: Variable interpolation {variable\_name} in messages is resolved at runtime using session \ context variables. #### Slots Slots capture data from agent goals. Each slot has four properties:


Property	Required	Description
name	yes	The key in the slots map
type	yes	string, number, boolean, object
description	yes	What this slot captures (max 200 chars)
optional	no	If true, slot is not required (default: false)

``` goals: search_character: description: User wants to search for a character slots: character_name: type: string description: 'Name of the character to search for' include_films: type: boolean description: 'Whether to include film appearances' optional: true max_results: type: number description: 'Maximum number of results to return' optional: true next: search_api ``` Note: Slots default to required. Only add optional: true when the slot is truly optional. #### Agent Node Agent nodes are the heart of conversational AI: ``` nodes: - main_agent: type: agent # System prompt - use YAML's literal block for multi-line system: | You are a helpful customer service agent. Be friendly but professional. When the user wants to check their balance, trigger the 'check_balance' goal. When the user wants to end the call, trigger the 'goodbye' goal. # Behavioral flags (all optional, default to false/0) single_turn: false take_initiative: false iteration_limit: 5 # Optional: memory identifier for conversation context memory_id: main_agent # MCP tools (optional) - references a tools node by name tools: customer_tools # See Tools Node section # Goals define how the agent routes goals: check_balance: description: User wants to check account balance slots: account_type: type: string description: 'Type of account (checking, savings)' next: balance_api goodbye: description: User is done with the conversation next: farewell # Fallback is REQUIRED when iteration_limit is set fallback: next: fallback_message # Error exit (optional) - runtime errors (e.g., LLM failure) error: next: error_handler - fallback_message: type: say message: I'm sorry, I didn't understand that. next: end - error_handler: type: say message: An error occurred. Let me transfer you. next: transfer_to_agent ``` **Customer v2 Data Structure:** ``` // Source: packages/model/src/flow/nodes/agent-node.interface.ts interface AgentNode extends Node { readonly type: NodeType.AGENT; // ← YFlow: type: agent name: string; // ← YFlow: node key (e.g., "main_agent") systemPrompt: string; // ← YFlow: system field iterationLimit?: number; // ← YFlow: iteration_limit singleTurn: boolean; // ← YFlow: single_turn takeInitiative: boolean; // ← YFlow: take_initiative memoryIdentifier?: string; // ← YFlow: memory_id tools?: string[]; // ← YFlow: tools (reference to tools node) goals: AgentGoal[]; // ← YFlow: goals map → AgentGoal[] } // Source: packages/model/src/flow/nodes/agent/agent-goal.interface.ts interface AgentGoal { name: string; // ← YFlow: goal key (e.g., "check_balance") description: string; // ← YFlow: description field slots: Slot[]; // ← YFlow: slots map → Slot[] } // Source: packages/model/src/flow/nodes/agent/slot.interface.ts interface Slot { name: string; // ← YFlow: slot key (e.g., "account_type") description: string; // ← YFlow: description field type: 'string' | 'number' | 'boolean'; // ← YFlow: type field required: boolean; // ← YFlow: optional (inverted) } ``` **Field Mapping:**


YFlow	Customer v2 Field	Notes
main_agent: (key)	name	Node name
type: agent	type: NodeType.AGENT	Enum value
system:	systemPrompt	Multi-line string
single_turn:	singleTurn	Boolean flag
take_initiative:	takeInitiative	Boolean flag
iteration_limit:	iterationLimit	Optional number
memory_id:	memoryIdentifier	Optional conversation context ID
tools:	tools	Reference to tools node name
goals:	goals: AgentGoal[]	Map → array conversion
fallback:	Exit with label "fallback"	Required when iteration_limit set
error:	Exit with label "error"	Optional runtime error exit

#### Menu Node Menu nodes are a specialized agent with DTMF (phone keypad) capabilities. They extend AgentNodeBase — same behavioral flags as Agent (iteration\_limit, take\_initiative): ``` nodes: - main_menu: type: menu # System prompt (same as agent — inherited from AgentNodeBase) system: | You are collecting menu entries. Present the options and wait for the user to press a key. # Behavioral flags (same as agent — inherited from AgentNodeBase) iteration_limit: 3 take_initiative: true # Optional: memory identifier for conversation context memory_id: main_menu options: '1': name: sales description: Press 1 for Sales next: sales_agent '2': name: support description: Press 2 for Support next: support_agent '0': name: operator description: Press 0 for a representative next: transfer_agent # Fallback when iteration_limit is exceeded (same as agent) fallback: next: menu_fallback - menu_fallback: type: say message: Let me connect you with someone who can help. next: transfer_agent ``` **Customer v2 Data Structure:** ``` // Source: packages/model/src/flow/nodes/menu-node.interface.ts interface MenuNode extends AgentNodeBase { readonly type: NodeType.MENU; // ← YFlow: type: menu options: MenuOption[]; // ← YFlow: options map → MenuOption[] } // AgentNodeBase provides: systemPrompt, iterationLimit, takeInitiative, memoryIdentifier // Source: packages/model/src/flow/nodes/menu/menu-option.interface.ts interface MenuOption { key: string; // ← YFlow: option key (e.g., "1") name: string; // ← YFlow: name field description: string; // ← YFlow: description field } ``` **Field Mapping:**


YFlow	Customer v2 Field	Notes
main_menu: (key)	nodeId (generated)	Node identifier
type: menu	type: NodeType.MENU	Direct mapping
system:	systemPrompt	Inherited from AgentNodeBase
iteration_limit:	iterationLimit	Inherited from AgentNodeBase
take_initiative:	takeInitiative	Inherited from AgentNodeBase
memory_id:	memoryIdentifier	Inherited from AgentNodeBase
options:	options: MenuOption[]	Map → array conversion
"1": (option key)	key: "1"	DTMF key (0-9, *, #)
name:	name	Option identifier
description:	description	Spoken option text (max 200 chars)
next: (in option)	Exit with label: "1"	Exit per option
fallback:	Exit with no label	Default exit

**Simple Menu Example:** ``` nodes: - quick_menu: type: menu system: Press 1 for yes, 2 for no iteration_limit: 1 options: '1': name: yes description: Confirm next: confirm '2': name: no description: Cancel next: cancel fallback: next: operator ``` #### API Node API calls to external services: ``` nodes: - get_balance: type: api # Reference integration and method by human-readable name integration: banking_api method: get_account_balance # Optional: resolved UUIDs (populated at save time, stripped on export) integration_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890' method_id: 'f9e8d7c6-b5a4-3210-fedc-ba0987654321' # Map slots to API parameters params: accountId: '{account_number}' accountType: '{account_type}' # Store result with prefix result_prefix: balance # Named exits exits: success: next: process_result failure: next: api_error ``` **Customer v2 Data Structure:** ``` // Source: packages/model/src/flow/nodes/api-call-node.interface.ts interface ApiCallNode extends Node { readonly type: NodeType.API_CALL; // ← YFlow: type: api apiName: string; // ← Display name (from integration label) integrationConnectionId: string; // ← YFlow: integration (resolved to UUID) methodName: string; // ← YFlow: method (display name) methodDefinitionId: string; // ← YFlow: method (resolved to UUID) variablePrefix: string; // ← YFlow: result_prefix requestVariables?: Record; // ← YFlow: params (converted) } ``` **Field Mapping:**


YFlow	Customer v2 Field	Notes
get_balance: (key)	nodeId (generated)	Node identifier
type: api	type: NodeType.API_CALL	Note: api → apiCall
integration:	apiName	Human-readable name (always present)
integration_id:	integrationConnectionId	Optional UUID (resolved at save time)
method:	methodName	Human-readable name (always present)
method_id:	methodDefinitionId	Optional UUID (resolved at save time)
params:	requestVariables	{var} → bare name
result_prefix:	variablePrefix	Result variable prefix
exits:	exits[]	Named exits → Exit[]

**Params Conversion:** ``` # YFlow params (with {variable} syntax) params: accountId: '{account_number}' accountType: '{account_type}' ``` ``` // Customer v2 requestVariables (bare variable names) requestVariables: { "accountId": "account_number", "accountType": "account_type" } ``` #### Transfer Node Transfer calls to human agents. Destination must use tel: or sip: prefix. A successful transfer \ hands the caller off — there is no return to the flow. Only the error exit returns to the flow. ``` nodes: - transfer_to_sales: type: transfer destination: tel:+15551234567 # Required: tel: or sip: prefix label: Sales Department # Optional: pass context via UUI (SIP only) context_variable: case_id # Error route (required) - called when transfer fails exits: error: next: transfer_failed - transfer_failed: type: say message: I couldn't complete the transfer. next: main_menu ``` **Destination Formats:** * tel:+18005551212 — E.164 telephone (recommended) * tel:+1-800-555-1212 — With dashes * sip: — Named SIP endpoint * sip:<1001@pbx.company.com> — Internal PBX extension **Customer v2 Data Structure:** ``` // Source: packages/model/src/flow/nodes/transfer-node.interface.ts interface TransferNode extends Node { readonly type: NodeType.TRANSFER; // ← YFlow: type: transfer destination: string; // ← YFlow: destination (tel:+1... or sip:...) label?: string; // ← YFlow: label integrationIdVariable?: string; // ← YFlow: context_variable } ``` **Field Mapping:**


YFlow	Customer v2 Field	Notes
transfer_to_sales: (key)	nodeId (generated)	Node identifier
type: transfer	type: NodeType.TRANSFER	Direct mapping
destination:	destination	Must start with tel: or sip:
label:	label	Display name for transfer
context_variable:	integrationIdVariable	UUI context (SIP only)
exits:	exits[0] (label: "error")	Error-only exit (type: "handoff")

**Validation Rules:** * destination is required and must start with tel: or sip: * exits: { error: } is required — there is no success exit (successful transfers leave the flow) * context\_variable (UUI) only works with sip: destinations #### Tools Node Tools nodes bind MCP integration tools to an agent. They define which MCP methods are available for the agent to call. ``` nodes: # Agent that can call MCP tools - retail_agent: type: agent system: | You are a helpful retail assistant. Use the sendProductLink tool to send product links via SMS. tools: retail_tools # Agent has ACCESS to these tools goals: done: next: farewell fallback: next: end # Tools definition - referenced by agent's `tools:` property - retail_tools: type: tools tools: - connection: retail_mcp # Human-readable name (always present) connection_id: 'a1b2c3d4-...' # Optional UUID (resolved at save, stripped on export) tools: - sendProductLink # Specific tools to expose - checkInventory integrations: retail_mcp: # ID - immutable label: 'Retail MCP Server' # Display name - can change type: mcp endpoint: https://api.example.com/mcp/sse auth: type: customheaders custom_headers: '{"x-api-key":"your-api-key"}' ``` **Key Points:** * Agent nodes reference tools via tools: \ * Tools nodes use type: tools and define available MCP connections * connection: references an integration by human-readable name (always present) * connection\_id: is the optional resolved UUID (populated at save time, stripped on export) * tools: lists specific MCP tools to expose to the agent (matched by name at runtime) * Multiple MCP connections can be listed in the tools: array **Customer v2 Data Structure:** ``` // Source: packages/model/src/flow/nodes/tools-node.interface.ts interface ToolsNode extends Node { readonly type: NodeType.TOOLS; // ← YFlow: type: tools tools: MCPConnection[]; // ← YFlow: tools array } // Source: packages/model/src/flow/nodes/tools/mcp-connection.interface.ts interface MCPConnection { readonly type: ToolType.MCP; connectionId: string; // ← YFlow: connection (resolved to UUID) tools: MCPTool[]; // ← YFlow: tools list } // Source: packages/model/src/flow/nodes/tools/mcp-tool.interface.ts interface MCPTool { name: string; // ← YFlow: tool name in list } // Source: packages/model/src/flow/nodes/tools/tool-type.enum.ts enum ToolType { MCP = 'MCP', INTERNAL = 'INTERNAL', } ``` **Field Mapping:**


YFlow	Customer v2 Field	Notes
retail_tools: (key)	nodeId (generated)	Node identifier
type: tools	type: NodeType.TOOLS	Direct mapping
tools:	tools: MCPConnection[]	Array of connections
connection:	(display name)	Human-readable name (always present)
connection_id:	connectionId	Optional UUID (resolved at save time)
tools: [sendProductLink]	tools: [{ name: "sendProductLink" }]	Tool names → MCPTool[]

--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.ixhello.com/ixhc2/technical-specifications/yflow-a-yaml-based-conversational-flow-language/node-types-reference.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.