Skip to main content

​
Adding a New Node Type

This guide walks through adding a new node type to Voiceblox. You’ll touch four files.

​
Step 1: Define the node template

In components/builder/nodeTemplates.ts, add a new entry to the nodeTemplates array: 
{
  nodeType: "my_node",
  label: "My Node",
  category: "conversation",     // or "component", "integration", "framework"
  provider: "my_provider",      // optional, for component nodes with multiple providers
  icon: MyIcon,                 // Lucide icon or custom SVG
  subtitle: "Short description",
  description: "Longer description for the AI generator",
  params: [
    {
      name: "myParam",
      label: "My Parameter",
      type: "string",
      placeholder: "Enter value..."
    },
    {
      name: "myEnum",
      label: "My Option",
      type: "enum",
      options: [
        { value: "option_a", label: "Option A" },
        { value: "option_b", label: "Option B" }
      ]
    }
  ],
  inputs: [
    { id: "in", type: "control", label: "In" }
  ],
  outputs: [
    { id: "output", type: "control", label: "Out" }
  ]
}

​
Step 2: Add connection rules

In components/builder/connectionRules.ts, add a rule for your new node: 
my_node: {
  inputs: {
    in: { maxConnections: 1 }
  },
  outputs: {
    maxConnections: 1,
    targets: [
      {
        nodeCategory: "conversation",
        excludeNodeTypes: ["start"],
        targetHandleId: "in"
      }
    ]
  }
}

​
Step 3: Handle in graph-to-config

In lib/agent/graph-to-config.ts, add handling in collectAllSteps() to extract your node’s parameters into the ConversationStep: 
if (node.nodeType === "my_node") {
  step.myParam = node.data.myParam as string
}
And add "my_node" to the StepType union in lib/agent/models.ts: 
type StepType = "start" | "timer" | "burst" | "end" | "webhook" | "opentalk" | "ifelse" | "categorize" | "my_node"

​
Step 4: Handle in the agent runtime

In agent/livekit.ts, add a case in VoicebloxAgent’s onUserTurn() handler (or the StepWatcher if it’s a step-level node) to define the runtime behavior: 
// In step-watcher.ts — add to onUserTurn()
case "my_node":
  return this.advance(current)

​
Testing

  1. Restart pnpm dev
  2. Find your node in the sidebar under its category
  3. Drag it onto the canvas and verify handles appear correctly
  4. Try connecting it to adjacent nodes and verify connection rules work
  5. Add it to a flow and run it in the playground to verify runtime behavior
  6. Ask the AI generator to add your new node type and verify it generates correctly

​
Checklist

  • Node template added to nodeTemplates.ts
  • Connection rules added to connectionRules.ts
  • StepType or config type updated in models.ts
  • Parameter extraction added to graph-to-config.ts
  • Runtime behavior added to livekit.ts or step-watcher.ts
  • Tested manually in the builder
  • Tested in the playground