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:

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:

Customer v2 Data Structure:

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:

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:

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:

Customer v2 Data Structure:

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)

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:

Customer v2 Data Structure:

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 nodes are a specialized agent with DTMF (phone keypad) capabilities. They extend AgentNodeBase — same behavioral flags as Agent (iteration_limit, take_initiative):

Customer v2 Data Structure:

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:

API Node

API calls to external services:

Customer v2 Data Structure:

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:

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.

Destination Formats:

Customer v2 Data Structure:

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.

Key Points:

  • Agent nodes reference tools via tools: <tools_node_name>

  • 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:

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[]

Last updated

Was this helpful?