Skip to main content

JSON Structure Reference

This document describes the JSON structure exported by Chatbot Flow Editor and provides technical details for integration with your own chatbot implementation.

JSON Structure Overview​

The exported JSON is an array of node objects representing your conversation flow:

[
{
"id": 1,
"title": "Welcome! How can I help you?",
"options": [
{ "label": "Technical Support", "nextId": 2 },
{ "label": "Billing Questions", "nextId": 3 }
],
"parentId": undefined,
"hierarchyPath": "1"
}
]

Node Object​

Each node in the flow has the following structure:

Properties​

PropertyTypeRequiredDescription
idnumber✅Unique identifier for the node
titlestring✅The message text displayed to users
optionsChatOption[]✅Array of response options (can be empty)
parentIdnumber | undefined❌ID of the parent node (undefined for root)
hierarchyPathstring❌Dot notation path (e.g., "1-2-1")

Example​

{
"id": 5,
"title": "What type of technical issue are you experiencing?",
"options": [
{ "label": "Login Problems", "nextId": 6 },
{ "label": "Software Bug", "nextId": 7 },
{ "label": "Performance Issue", "nextId": 8 }
],
"parentId": 2,
"hierarchyPath": "1-1"
}

ChatOption Object​

Each option represents a user choice that leads to another node:

Properties​

PropertyTypeRequiredDescription
labelstring✅Text displayed to the user
nextIdnumber✅ID of the destination node

Example​

{
"label": "Yes, I need help with that",
"nextId": 42
}

Complete Flow Example​

Here's a complete example of a customer support flow:

[
{
"id": 1,
"title": "Welcome to our support! How can we assist you today?",
"options": [
{ "label": "Technical Issues", "nextId": 2 },
{ "label": "Billing Questions", "nextId": 3 },
{ "label": "General Information", "nextId": 4 }
],
"hierarchyPath": "1"
},
{
"id": 2,
"title": "I'll help you with technical issues. What's the problem?",
"options": [
{ "label": "Can't log in", "nextId": 5 },
{ "label": "App is crashing", "nextId": 6 },
{ "label": "Feature not working", "nextId": 7 }
],
"parentId": 1,
"hierarchyPath": "1-1"
},
{
"id": 3,
"title": "I can help with billing questions. What do you need to know?",
"options": [
{ "label": "View my bill", "nextId": 8 },
{ "label": "Payment issues", "nextId": 9 },
{ "label": "Cancel subscription", "nextId": 10 }
],
"parentId": 1,
"hierarchyPath": "1-2"
},
{
"id": 4,
"title": "What general information would you like?",
"options": [
{ "label": "Company hours", "nextId": 11 },
{ "label": "Contact information", "nextId": 12 }
],
"parentId": 1,
"hierarchyPath": "1-3"
},
{
"id": 5,
"title": "For login issues, please try resetting your password. If that doesn't work, contact our technical team.",
"options": [],
"parentId": 2,
"hierarchyPath": "1-1-1"
}
]

Flow Navigation Pattern​

Here's a basic pattern for navigating through the flow:

class FlowNavigator {
constructor(flowData) {
this.nodes = new Map();
flowData.forEach(node => {
this.nodes.set(node.id, node);
});
this.currentNodeId = 1; // Start at root
}

getCurrentNode() {
return this.nodes.get(this.currentNodeId);
}

selectOption(optionIndex) {
const currentNode = this.getCurrentNode();
if (currentNode && currentNode.options[optionIndex]) {
this.currentNodeId = currentNode.options[optionIndex].nextId;
return this.getCurrentNode();
}
return null;
}

reset() {
this.currentNodeId = 1;
}
}

JSON Schema​

You can validate exported JSON against this schema:

{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "array",
"items": {
"type": "object",
"required": ["id", "title", "options"],
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"title": {
"type": "string",
"minLength": 1
},
"options": {
"type": "array",
"items": {
"type": "object",
"required": ["label", "nextId"],
"properties": {
"label": {
"type": "string",
"minLength": 1
},
"nextId": {
"type": "integer",
"minimum": 1
}
}
}
},
"parentId": {
"type": "integer",
"minimum": 1
},
"hierarchyPath": {
"type": "string"
}
}
}
}

Validation Function​

function validateFlow(flowData) {
const errors = [];
const nodeIds = new Set();

// Check for duplicate IDs
flowData.forEach(node => {
if (nodeIds.has(node.id)) {
errors.push(`Duplicate node ID: ${node.id}`);
}
nodeIds.add(node.id);
});

// Check for valid option targets
flowData.forEach(node => {
node.options.forEach(option => {
if (!nodeIds.has(option.nextId)) {
errors.push(`Node ${node.id} has option pointing to non-existent node ${option.nextId}`);
}
});
});

// Check for root node
if (!nodeIds.has(1)) {
errors.push('Missing root node with ID 1');
}

return errors;
}

TypeScript Definitions​

If you're using TypeScript, here are the type definitions:

interface ChatOption {
label: string;
nextId: number;
}

interface ChatNode {
id: number;
title: string;
options: ChatOption[];
parentId?: number;
hierarchyPath?: string;
}

type ChatbotFlow = ChatNode[];

Flow Properties​

Node IDs​

  • Always start with ID 1 as the root node
  • IDs are unique across the entire flow
  • Sequential numbering is recommended but not required

Hierarchy Paths​

  • Root node: "1"
  • First child of root: "1-1"
  • Second child of root: "1-2"
  • First child of first child: "1-1-1"

Parent Relationships​

  • Root node has no parentId
  • All other nodes should have a parentId pointing to their parent
  • Parent relationships are automatically established when creating flows

Options and Navigation​

  • Empty options array indicates an end node (conversation termination)
  • All nextId values must reference existing nodes
  • Options are presented to users in the order they appear in the array

Best Practices​

Data Structure​

  • Keep node IDs simple and sequential
  • Use descriptive titles that clearly communicate the message
  • Write option labels that users will understand
  • Validate all nextId references before using the flow

Flow Design​

  • Always include a root node with ID 1
  • Provide clear conversation paths
  • Include appropriate end nodes for conversation closure
  • Test all possible navigation paths