Overview

This guide shows how to build custom chatbot or AI applications that use HyperFlow published flow-graphs as their backend. You'll learn the Control API patterns, state management, streaming responses, and file uploads by examining the production-tested implementation patterns from HyperFlow's embeddable chatbot.

What You'll Build: A custom client application (web, mobile, or desktop) that communicates with published HyperFlow flow-graphs to provide an AI assistant experience similar to ChatGPT, Claude, or custom conversational UIs.

Prerequisites:

• A published HyperFlow flow-graph (see user guides on publishing)
• Basic understanding of async/await JavaScript patterns
• Familiarity with REST APIs and long-polling

Architecture Overview

Communication Model

HyperFlow uses a long-polling architecture for real-time bidirectional communication:

┌─────────────┐                           ┌─────────────────┐
│   Client    │                           │  HyperFlow API  │
│    App      │                           │  (Flow-graph)   │
└─────┬───────┘                           └────────┬────────┘
      │                                             │
      │  1. POST /control/start                     │
      │  {flowGraphID, queryParams}                 │
      │─────────────────────────────────────────────>
      │                                             │
      │  {sessionID, stepIndex, responses:[...]}    │
      <─────────────────────────────────────────────│
      │                                             │
      │  2. POST /control/progress (long-poll)      │
      │  {sessionID, stepIndex, progress:[...]}     │
      │─────────────────────────────────────────────>
      │                                             │
      │       [Server waits for flow-graph]         │
      │              ...holding...                  │
      │                                             │
      │  {sessionID, stepIndex, responses:[...]}    │
      <─────────────────────────────────────────────│
      │                                             │
      │  3. Immediately send next /control/progress │
      │─────────────────────────────────────────────>
      │              (repeat)                       │

Key Points:

• Sessions are stateful - each user interaction maintains context via sessionID
• Long-polling enables server-push without WebSockets
• Flow-graphs can request user input, send messages, stream LLM responses
• Client immediately re-polls after receiving responses (true long-polling)

Core Endpoints

// Base URL: <https://hyperflow-ai.com> or your deployment
const controlAPI = {
    start: "/api/flowgraph/control/start",           // Initialize session
    progress: "/api/flowgraph/control/progress",     // Send/receive updates
    streaming: "/api/flowgraph/control/streaming",   // Poll for LLM streaming
};

Implementation Guide

1. Session Initialization