Skip to main content

Flow Types

Each flow works like a function with a defined input and output. The Start node defines the inputs of the flow, and each End node defines a possible output. Understanding how those two nodes behave is the key to making flows reusable and compatible with every runtime that BotDojo supports.

For a chatbot, the input is typically the user's message, and the output is the bot's reply. A flow can receive more than text though—inputs and outputs are defined with JSON Schema, so you can add structured data, arrays, files, or Booleans when your automation needs them.

Start node​

  • Every flow must include exactly one Start node. Validation fails as soon as a second Start node is added.
  • The Input Schema property controls the fields that enter the flow. By default it contains a single string (for text input), but you can add additional properties, change types, and mark them as required to match the data your flow expects.
  • Start nodes can subscribe to triggers (integrations, schedules, or voice calls). When a trigger is attached, the trigger payload is exposed as additional Start node outputs so you can branch immediately on trigger data.

When you adjust the input schema, keep your target flow type in mind. Some flow types enforce a specific schema shape—see the flow type table below before adding or removing fields.

End node​

  • Flows can have one or more End nodes. Each End node represents a termination point and its own Output Schema describing what gets returned.
  • The default output schema contains a single text_output string. You can replace it with a custom schema to return structured data, arrays, or files.
  • Chat flows include a Show property in chat option. Use it when your output schema holds multiple fields but you still want a single string rendered in chat. The chosen property must exist in the output schema and be a string.

BotDojo automatically infers the flow type from the Start and End node schemas. Setting the flow type manually in Flow Settings → Flow Type enables additional validations that make sure both nodes stay compatible with runtime expectations.

Flow types and schema requirements​

Standard flow​

  • Default for new flows. Any Start node schema is allowed, so you can mix strings, numbers, Booleans, arrays, files, or nested objects.
  • End nodes can return any schema that matches your downstream consumers. There are no type-specific settings—use the general tabs (General, Properties, Tool Config, Share, Runtime Options) to manage metadata and packaging.

Chat flow​

  • Start node must expose exactly one string field for the user message. You may optionally include a file or image upload (single item or array), a model context field for shared conversation state, and a resources field for preloaded documents. Additional fields cause validation errors because chat surfaces expect a predictable payload.
  • End nodes must either return a single string property or use Show property in chat to point to the string field that should be surfaced to end users.
  • Chat-compatible flows plug directly into every BotDojo chat interface—BotDojo Chat, embedded widgets, Slack, Microsoft Teams, and any other chat connector—without additional mapping. As long as the Start/End schemas stay compatible, the flow can be published everywhere a chat session is supported.
  • Flow settings offer dedicated Chat options: craft a Markdown welcome message, toggle inline evaluations, automatically generate session names from user messages, and choose whether to display retrieval sources. These settings are only applied when the Start schema remains chat-compatible.

Voice flow​

  • Start node must match the voice input structure, which provides at least the caller transcript (user_transcript) and may include phone metadata when the runtime supplies it.
  • End node must return the voice output structure. A text_output string is required, with optional escalate_to_agent and hang_up_call Booleans to steer the call session.
  • Flow settings expose Voice controls once the type is enabled: assign or purchase phone numbers, pick which published version answers calls, choose a synthetic or cloned voice, configure greetings (and whether callers can interrupt them), define escalation phone numbers, tune keyword boosts for speech recognition, and specify post-call instructions. Saving these settings updates the flow definition and the Twilio integration trigger behind the scenes.

Evaluation flow​

  • Start node can accept any schema that supplies the signals your evaluation needs (prompt, candidate response, reference answer, metadata, etc.). Choose property names that make sense for your scoring logic.
  • End node must emit the standard evaluation result payload. The structure supports a Boolean passed flag, numeric score, string classification, descriptive reason, an error field for failures, and an open-ended meta object for structured details.
  • Flow settings include an Evaluation tab where you define the metric label, internal variable name, description, illustrative icon, category tags, and output mode (metric, pass/fail, or multi-class classification). Those values determine how the evaluation appears in catalogs and automate validation for the End node schema.

Chunker flow​

  • Start node must use the chunker input shape. It carries file metadata (indexId, storagePath, fileName, contentType, optional metaData) and a chunks array describing the current segments.
  • End node must return the chunker output shape: a chunks array in the same format (content, optional metadata, sequence number). Your flow can rewrite, merge, or enrich chunks before returning them.
  • Flow settings add a Use as Custom Chunker tab. It confirms the Start/End schemas are correct, lets you flag the flow for reuse across indexes, and packages it so document pipelines can pick it up as a chunking strategy.

Model context flow​

  • Start node accepts a model context payload. At minimum it includes a model_context object (or array of objects) describing the reusable context state—cards, instructions, resource references, and tool availability.
  • End node must return the same structure so downstream chat or agent flows can update and persist the context. Validation ensures the output remains compatible with the model context runtime.
  • Model context flows package far more than plain text. The runtime wires together prompts, tool definitions, and resource cards (see the Model Context Manager node) so agents can discover and enable the context they need. These bundles also expose an MCP endpoint, allowing you to export the flow and host it as an MCP server for external clients.

By aligning your Start and End node schemas with the expected flow type, you ensure BotDojo can deploy, test, and reuse your flows across chat, voice, evaluation, context-sharing, and data-processing scenarios without additional wiring.